For organizations
Deployment guide

Self-hosted Conflux: setup

Everything IT needs to run Conflux.Server, connect an identity source and map directory groups to teams.

Self-hosted

Conflux.Server is a single Go binary, or the container built from the repository Dockerfile, in front of a PostgreSQL database. There are no queues, caches or other services to run, and the token signing key is generated on first boot.

  • PostgreSQL 13 or newer
  • The server binary, or the Docker image built from Conflux.Server
  • A public URL for the server (PUBLIC_BASE_URL), for example https://conflux.acme.com
  • Network reachability from the server to your identity provider or a domain controller
DATABASE_HOST=postgres.acme.local
DATABASE_USERNAME=conflux
DATABASE_PASSWORD=change-me
DATABASE_NAME=conflux
PUBLIC_BASE_URL=https://conflux.acme.com
INSTANCE_NAME=Acme
ADMIN_EMAILS=admin@acme.com
AUTO_JOIN_ORG=true
docker build -t conflux-server .
# apply database migrations once
docker run --rm --env-file .env --entrypoint migrate conflux-server \
  -path /app/migrations -database "postgres://conflux:change-me@postgres.acme.local:5432/conflux?sslmode=disable" up
# start the server on :8080
docker run -d --name conflux-server --env-file .env -p 8080:8080 \
  --entrypoint ./server conflux-server

Choose your identity source

AUTH_MODE decides how people sign in. In both modes the server issues its own short-lived access tokens and rotating refresh tokens; the hosted service on conflux.uz is unaffected.

OpenID Connect

The desktop app opens the system browser and redirects to your identity provider. Discovery is automatic, so the only extra configuration is a client id and secret.

Microsoft Entra IDOktaKeycloakGoogle WorkspaceAD FS 2016+
  • Login: system browser, redirect to your IdP
  • Group sync: at every login from the groups claim; background re-sync with Entra ID via Microsoft Graph (OIDC_GRAPH_SYNC=true)
  • Extra dependency: none
AUTH_MODE=oidc
OIDC_ISSUER=https://login.microsoftonline.com/<tenant-id>/v2.0
OIDC_CLIENT_ID=...
OIDC_CLIENT_SECRET=...
OIDC_GRAPH_SYNC=true          # Entra ID only: background re-sync via Graph

LDAP / Active Directory

Username and password are posted straight to the server, which binds against a domain controller over LDAPS with a read-only service account. Defaults match standard Active Directory: sAMAccountName or userPrincipalName as the login, objectGUID as the stable id, memberOf for groups.

  • Login: domain username and password, no browser
  • Group sync: at login and on every scheduled re-sync
  • Extra dependency: LDAPS reachable from the server and a read-only bind account
AUTH_MODE=ldap
LDAP_URL=ldaps://dc1.acme.local:636
LDAP_BIND_DN="CN=svc-conflux,OU=Service Accounts,DC=acme,DC=local"
LDAP_BIND_PASSWORD=...
LDAP_BASE_DN="DC=acme,DC=local"

Groups become teams

GROUP_MAP maps directory groups to Conflux teams and organization roles. Membership is applied at login and on every scheduled re-sync, and it cannot be edited by hand in the app.

GROUP_MAP="CN=Dev-Backend,OU=Groups,DC=acme,DC=local=team:Backend;CN=QA,OU=Groups,DC=acme,DC=local=team:QA;CN=Conflux-Admins,OU=Groups,DC=acme,DC=local=org:admin"
LDAP_MATCHING_RULE_IN_CHAIN=true   # resolve nested AD groups
SYNC_INTERVAL=15m
  • The left side is the group DN (LDAP) or the group id or name from the claim (OIDC); the right side is team:<Name> or org:admin.
  • The first person from ADMIN_EMAILS to sign in becomes the owner of the organization named INSTANCE_NAME. AUTO_JOIN_ORG=true lets everyone else in as a member.
  • memberOf lists only direct membership. Set LDAP_MATCHING_RULE_IN_CHAIN=true to resolve nested groups.
  • Memberships that come from the directory are locked in the app and labelled "Managed by Active Directory".

Lifecycle from your directory

Access follows the directory, not the app. Nobody has to remember to offboard someone in Conflux.

SYNC_INTERVAL=15m
  • Scheduled re-sync every 15 minutes by default (SYNC_INTERVAL=15m). Set it to 0 to sync only at login.
  • Disabled or deleted in AD: the Conflux account is disabled and every refresh token is revoked, so the desktop app is signed out of the work account on its next request.
  • Removed from a mapped group: the user leaves the team. Added to one: they join it.
  • Personal accounts on conflux.uz are untouched; only the work account is affected.

One desktop app

The same Conflux desktop app works with conflux.uz and with any number of company servers, side by side. Work and personal accounts stay separate and you switch between them in the account menu.

  1. 1Open the account menu and choose "Sign in with company SSO".
  2. 2Enter your server address, for example conflux.acme.com. The app discovers the auth mode automatically.
  3. 3OIDC opens the browser at your identity provider; LDAP asks for your domain username and password.
conflux.uz+conflux.acme.com·

Updating

Conflux.Server tags a release image for every version, so a self-hosted install updates by pulling a new tag rather than rebuilding from source. Update the server first, then the clients.

  1. 1Pull and run the new server image. The old server keeps talking to both old and new Desktop/CLI builds while the rollout is in progress — nothing breaks mid-update.
  2. 2Roll out Desktop and the CLI tools to your users at your own pace, once the server is up.
  3. 3Once everyone has upgraded, optionally raise the floor with MIN_CLIENT_PROTOCOL, MIN_DESKTOP_VERSION and MIN_CLI_VERSION so old builds are turned away with a clear "please update" instead of silently drifting out of sync.
docker pull ghcr.io/uzdevid/conflux-server:0.7.0   # or :0.7, or :latest
# apply any new database migrations (safe to run with none pending)
docker run --rm --env-file .env --entrypoint migrate ghcr.io/uzdevid/conflux-server:0.7.0 \
  -path /app/migrations -database "postgres://conflux:change-me@postgres.acme.local:5432/conflux?sslmode=disable" up
# restart with the new image
docker stop conflux-server && docker rm conflux-server
docker run -d --name conflux-server --env-file .env -p 8080:8080 \
  ghcr.io/uzdevid/conflux-server:0.7.0
# raise the floor once everyone has upgraded (optional, manual)
# MIN_CLIENT_PROTOCOL=2
# MIN_DESKTOP_VERSION=0.7.0
Current compatibility
ServerMin DesktopMin CLIProtocol
0.7.00.7.0no floor set yet (MIN_CLI_VERSION)2

Server 0.7.0 defaults to MIN_CLIENT_PROTOCOL=1 and empty MIN_DESKTOP_VERSION/MIN_CLI_VERSION, so nothing is cut off out of the box — the columns above are the levers you set once you're ready to require the newer clients, not a hard requirement today.