GrantID - Setup on Docker
To install an on-premises instance of GrantID on Docker, follow the steps below. For other platforms, click here.
For Docker-based setup the following image is provided on Docker Hub:
The currently recommended image is
Available moving tags:
4.2points to the latest 4.2.x image (currently recommended)
4points to the lastest 4.x image
stablepoints to the latest stable image
This image requires:
- Blob storage shared between all containers running the image -- see Blob Storage configuration
- Volume shared between all containers running the image mounted on
/var/keys, used to store data protection keys. Files on this volume are few, seldom written to and read only during container startup, therefore this can be any low-performing shared volume provided by whatever orchestrator you use.
- PKI SDK license (in Base64 format)
- Web PKI license (Base64/binary format) -- only needed for certificate sign in
- DNS entries previously created for the domains mentioned on the planning section
- Connection string to a previously created SQL Server or PostgreSQL database
The container for this image is configured using environment variables. Get the sample environment file for a template to fill in the image's settings.
To fill the
Application__TempTokenPassword setting, generate a 256-bit key to encrypt sensitive data:
docker run lacunasoftware/psc:1 -- gen-enc-key
To fill the
Application__SigningCertificatePfxPassword settings, generate a PFX file containing a self-signed certificate to sign OAuth tokens:
docker run lacunasoftware/psc:1 -- gen-cert "Your GrantID Name" SOME_PASSWORD
The output will be similar to:
$ docker run lacunasoftware/psc:1 -- gen-cert "Patorum ID" "1234" PSC entrypoint invoked Starting application # # PFX # MIIPwQ...AAA= # # Certificate # -----BEGIN CERTIFICATE----- MIIE... ....... ....... -----END CERTIFICATE----- # # Thumbprint # 0123...
Copy the entire contents of the PFX section (all as a single line) over to the
Application__SigningCertificatePfxContent setting (in the example above,
MIIPwQ...AAA=, in reality this would be
a single line with ~5000 characters) and fill the
Application__SigningCertificatePfxPassword setting with the same password you used on the generation command.
Additional settings can be found at the GrantID Settings page.
Pull the latest stable image, get the sample configuration file, the required environment variables and run the container.
Start with only one container as in the first startup, the database tables will be created (more containers could create a race condition). Once the initial startup is complete, you may run as many containers as you want.
Then, follow the steps on GrantID post-installation to complete the installation procedure.
GrantID is composed of three services which the image exposes in a single container, listening on the following ports:
|Service||Default Port||Environment variable to customize|
If you need one image per service for fine-grained control of your containers contact us.
Your environment configuration must direct traffic from the application domains to the container ports in the following way:
|Domain type||Example||Destination container port|
|Base domain||id.yourcompany.com||5011 (Auth Server)|
|Login||login.id.yourcompany.com||5011 (Auth Server)|
|API||api.id.yourcompany.com||5010 (Identity Service)|
In a production environment you would typically use a Docker orchestrator to handle issues such as routing and a dedicated database server (or a IaaS database offering), but for testing purposes you can run an instance of GrantID with an instance of PostgreSQL with Docker alone and emulate the routing by setting the DNS resolution of app domains to the loopback interface.
Start by appending the entries below to your OS's hosts file (on Windows C:\Windows\System32\drivers\etc\hosts, on Linux /etc/hosts) to map the auth server domains back to the loopback interface (replace the domains with your base and login domains):
127.0.0.1 id.yourcompany.com 127.0.0.1 login.id.yourcompany.com
Create a volume for the database server:
docker volume create grantid_sql
Start it with a password of your choice (replace
docker run --name grantid_sql -v grantid_sql:/var/lib/postgresql/data -p 5432:5432 -e "POSTGRES_PASSWORD=SOME_PASS" -d postgres
Check the container logs for any errors:
docker logs -f grantid_sql
This can take a few minutes. Once the database server is up and running, hit CTRL+C to exit the logs.
Create a volume to use as blob storage and another one to store data protection keys:
docker volume create grantid_data docker volume create grantid_keys
Then, download the sample environment file, save it with name grantid.env and fill it out.
On the connection string configuration, use the value below replacing
HOST_IP with the IP address of the host and
SOME_PASS with the
password you chose for PostgreSQL:
Set the URL settings as follows (replace the auth server URL with your base domain):
Application__AuthServerUrl=http://id.yourcompany.com/ Application__ConsoleUrl=http://localhost:8080/ Application__UseSsl=False
Now, let's run the container with the configuration file, mounting the volumes
/var/keys and exposing the
container's auth server port (5011) on the host's port 80 and the container's console port (5012) on the host's port 8080:
docker run --name grantid --env-file grantid.env -v grantid_data:/var/app -v grantid_keys:/var/keys -p 80:5011 -p 8080:5012 -d lacunasoftware/grantid:4.2
If given a credential with enough privileges, GrantID will attempt to create the target database on the server (which is what will happen in this case)
Check the container logs for any configuration errors:
docker logs -f grantid
If everything is configured correctly, you should be able to access the GrantID console on localhost:8080
Remember to follow the steps on GrantID post-installation to complete the installation procedure.