Skip to main content

🐳 Docker

OpenUEM can be tested using Docker containers that are hosted in Docker Hub

You can use docker compose to install all OpenUEM components in a single machine following these steps:

1. Get the docker-compose file​

Clone the openuem-docker repository:

git clone https://github.com/open-uem/openuem-docker

2. Create .env file with environment variables​

Use the file named .env-example file to create a .env file

note

The file must be named .env without extension and with a dot before the env word as required by Docker to read the environment variables

In the .env file, edit the environment variables that docker compose will use to build and get the containers up and running.

warning

You should set the Postgres database user and password in the init.sh file inside the postgres\build as defaults used are dummy, unsafe values that should not be used in production

psql -v ON_ERROR_STOP=1 --username "postgres" <<-EOSQL
CREATE DATABASE openuem;
CREATE USER **YOUR_USER** WITH ENCRYPTED PASSWORD '**YOUR PASSWORD**';
GRANT ALL PRIVILEGES ON DATABASE openuem TO **YOUR_USER**;
ALTER DATABASE openuem OWNER TO **YOUR_USER**;
EOSQL

Here are the possible environment variables that can appear in the .env file.

NameDescriptionOptionalExample value
SERVER_NAMEThe name of the server where the console is hostednoserver.example.com
POSTGRES_PORTThe port number where the database service should be foundno5432
DATABASE_URLThe database url in format postgres://user:password@openuem-db-1:port/openuemnopostgres://test:test@openuem-db-1:5432/openuem
ORGNAMEYour organization's namenoOpenUEM
ORGPROVINCEYour organization's provinceyesValladolid
ORGLOCALITYYour organization's localityyesValladolid
ORGADDRESSYour organization's addressyesMy org's address
COUNTRYYour organization's countrynoES
OCSP_PORTThe port used by the OCSP responderno8000
NATS_SERVERThe domain name used by the NATS servernoThe value of SERVER_NAME
NATS_PORTThe port used by the NATS serverno4433
NATS_SERVERSThe NATS service urlnoserver.example.com:4433
REVERSE_PROXY_SERVERIf you want to use a reverse proxy, set the domain name that you want to use to visit the consoleyesconsole.example.com
REVERSE_PROXY_AUTH_PORTIf you want to use a reverse proxy, set the port that will be used to answer for authyes1340
OCSPThe URL for the OCSP responder servicenohttp://server.example.com:8000
DOMAINYour DNS domainnoexample.com
CONSOLE_PORTThe port used by the consoleno1323
AUTH_PORTThe port used by the auth serverno1324
JWT_KEYThe key used to encrypt JWT tokens for user registrationnoaverylongsecret
TZThe timezone used by OpenUEM containersyesEurope/Madrid

server.example.com should be resolved by your DNS service if you want remote agents to be able to contact OpenUEM components.

tip

If you don't have a DNS you can use extra_hosts in the docker_compose.yml to add entries for the containers as if you were using /etc/hosts

Reference: https://docs.docker.com/reference/compose-file/build/#extra_hosts

Extra hosts

danger

It's strongly recommended to change the JWT key with a random 32 characters long string

3. Use a reverse proxy (Optional)​

You can run OpenUEM behind a reverse proxy. Caddy can be used and is supported for this deployment with docker compose.

First you must set the REVERSE_PROXY_SERVER and REVERSE_PROXY_AUTH_PORT env variables in the .env file and the REVERSE_PROXY_SERVER domain must be resolved by a DNS server.

Second you must uncomment these lines and watch that the right indentation is set:

  # caddy:
# image: caddy:latest
# restart: always
# profiles: ["caddy"]
# env_file:
# - .env
# ports:
# - "443:443"
# - $REVERSE_PROXY_AUTH_PORT:$REVERSE_PROXY_AUTH_PORT
# volumes:
# - "./caddy/Caddyfile:/etc/caddy/Caddyfile"
# - "./certificates/ca/ca.cer:/etc/caddy/ca.cer"
# - "./certificates/console/proxy.cer:/etc/caddy/proxy.cer"
# - "./certificates/console/proxy.key:/etc/caddy/proxy.key"
# - caddy_data:/data
# - caddy_config:/config


# caddy_data:
# driver: local
# caddy_config:
# driver: local

4. Launch docker compose command​

Where the compose.yaml file and the .env files are located, launch OpenUEM with the following commands:

docker compose --profile init up -d --build

Once we run that command, we should see that the database service is healthy and ready:

 βœ” Network openuem_default  Created
βœ” Volume "openuem_pgdata" Created
βœ” Container openuem-db-1 Healthy
βœ” Container openuem-certs Started

Also, we should see that a certificates folder has been created containing all the required certificates:

Certificates folder

warning

The generation of certificates can take some time, don't go to the next step until you check that certificates have been indeed created. If you find two files under the agents folder and one pfx file inside the users folder, you're good to go.

Now, it's time to start OpenUEM's components

docker compose --profile openuem up -d --build

We should see that all components have started:

 βœ” Volume "openuem_jetstream" Created
βœ” Container openuem-ocsp-responder-1 Started
βœ” Container openuem-nats-server Started
βœ” Container openuem-console-1 Started
βœ” Container openuem-notification-worker-1 Started
βœ” Container openuem-cert-manager-worker-1 Started
βœ” Container openuem-agents-worker-1 Started

If you want to use Caddy as a reverse proxy:

docker compose --profile caddy up -d

The Caddy container should be created and started:

 βœ” Container openuem-caddy-1  Started

If we want to stop OpenUEM we should run the following commands:

docker compose --profile openuem down
docker compose --profile init down

If you're using the Caddy option you can stop it with:

docker compose --profile caddy down
warning

If you find any error trying to launch the services, run the docker compose down commands shown above, remove the volumes and the certificates folder and start again

sudo rm -rf certificates
docker volume rm openuem_jetstream
docker volume rm openuem_pgdata

And if you use the Caddy option

docker volume rm openuem_caddy_config
docker volume rm openuem_caddy_data

Open an issue with all the possible information if you can't start OpenUEM with Docker

5. Trust in digital certificates created​

Before we can visit OpenUEM's console, we must import two digital certificates to our browser, the Certificate Authority certificate (ca.cer) and the user's certificate to log in. You have a guide explaining how to import certificates here

Next to the compose .yaml file you’ll find a certificates folder containing all the certificates that OpenUEM has created and that are required to run.

6. Visit OpenUEM's Console​

Now open https://SERVER_NAME:CONSOLE_PORT (replace the values that you've set in your .env file) and you should see OpenUEM's console

note

If you've set a reverse proxy the url should be https://REVERSE_PROXY_SERVER

Console LogIn

Finally, log in user your admin certificate and read how to install and add your first agent.

note

If you see any certificates error, please ensure that you've imported the right certificates in the right certificate stores of your browser

7. Update​

To update the Docker containers, use docker compose:

docker compose pull

docker compose --profile openuem up --force-recreate -d --build

And if you use the Caddy option

docker compose --profile caddy up --force-recreate -d