Docker Compose with Dex Identity Provider

This guide will show you how-to self-host dboxed with dex  as the Identity Provider.

The strength of Dex is its simplicity, allowing you to fully configure it via a config file. It can also be configured to provide statically configured users, which is good enough for many homelab setups.

Requirements

You’ll need a few things for this guide:

• A publicly reachable server (e.g., a Hetzner cloud server) with ports 80 and 443 open.
• A public DNS entry pointing to the public IP of your server
• A recent Docker Engine installation on your server. Follow the official installation instructions  for details.

Clone the dboxed-selfhost repo

SSH into your server and clone the public selfhost repo:

git clone https://github.com/dboxed/dboxed-selfhost.git
cd compose-dex

From now on, perform all shell commands inside this directory.

Prepare Variables

The repository comes with example/template .env files named .env.example. You need to copy this file and name it .env:

cp .env.example .env

After copying it, open it in your favorite editor and go through all variables and set proper values. The example env file contains comments that try to explain each value. The most important ones are the database and admin passwords and the dboxed hostname.

For the database and admin passwords, use unique random passwords. Please note that changing the database passwords after the initial deployment will require some additional steps not covered by this guide.

Also ensure that the dboxed hostname you set is properly configured in your DNS provider. The DNS entry must point to the public IP of your server.

The DBOXED_VERSION and DBOXED_FRONTEND_VERSION variables are set to latest by default. You can pin them to a fixed release version instead.

Persistence

The example env file uses /var/lib/dboxed-server for the default storage location. This directory will contain the postgres database and other files required for persistence. Please consider a proper backup strategy for this directory as losing this data will mean serious data loss.

Deploying

To start dboxed, run:

docker compose up -d

Upgrading

To upgrade dboxed, update the DBOXED_VERSION and DBOXED_FRONTEND_VERSION fields and then ru-run docker compose up -d. In case you used latest for both variables, add --pull=always to the docker compose command.

Accessing dboxed

To access your freshly installed instance of dboxed, access the URL at https://DBOXED_HOSTNAME.

Of course, you’ll have to replace DBOXED_HOSTNAME with the host name you chose at the beginning.

To use the CLI with your self-hosted instance, add --api-url=https://DBOXED_HOSTNAME when running dboxed login.