Skip to content

Self-hosting Consoletium

Most companies use Consoletium hosted at <company>.consoletium.com, where we run the servers, backups and upgrades. Larger companies, and those that must keep data on their own infrastructure, can run the same software themselves under an annual licence. This section is for their IT team.

What you need

  • A Linux server: 4 vCPU and 8 GB of memory for up to about 50 users; 2 vCPU / 4 GB is enough for a trial. Ubuntu 24.04 is what we test on.
  • Docker Engine with the Compose plugin (version 2.24 or later).
  • A hostname such as erp.yourcompany.com with a DNS record pointing at the server, and ports 80 and 443 open to your users. Certificates are issued automatically by Let's Encrypt.
  • Your licence file, from Consoletium. Without one the system runs read-only.
  • Optional: an Anthropic API key, if you have the AI Agent & Insights module.

What runs

Container Does
db PostgreSQL 16, holding everything except files.
backend The API. Runs as a non-root user.
jobs The same image, running the scheduled jobs every five minutes: the mail queue, exchange rates, scheduled searches, the cycle-count rota.
frontend The web application's files.
proxy Caddy: HTTPS, security headers, and routing /api to the backend.

Attachments, uploads and the licence live in the erpdata volume; the database in pgdata. Back up both (see Backups).

Install

  1. Get the release. With your licence, Consoletium sends the release archive for your version and a token for the image registry. Unpack the archive on the server (say in /srv/consoletium) and sign in to the registry with docker login ghcr.io.

  2. Configure. Copy .env.example to .env and fill it in:

    Setting Value
    POSTGRES_PASSWORD A long random password.
    SECRET_KEY openssl rand -hex 32. Changing it later signs everybody out.
    PAYROLL_ENCRYPTION_KEY openssl rand -base64 32 \| tr '+/' '-_'. Encrypts employee bank details; keep a copy in your password manager, because a backup cannot be read without it.
    DOMAIN Your hostname, e.g. erp.yourcompany.com.
    COMPANY_NAME, COUNTRY, BASE_CURRENCY Your legal name; SG with SGD, or MY with MYR.
    DEPLOYMENT_MODE self_hosted.
    ERP_IMAGE The released image, e.g. ghcr.io/consoletium/consoletium-erp:0.9.0. Leave blank to build from the source instead.
    ANTHROPIC_API_KEY, AI_CAP_USD Optional; see AI features.

    Keep .env readable by root only (chmod 600 .env).

  3. Get the images.

    docker compose pull       # with ERP_IMAGE set
docker compose build      # builds the frontend, and the backend if ERP_IMAGE is blank

  4. Create the database and your company.

    docker compose run --rm backend python -m app.seed.db_migrate upgrade
docker compose run --rm backend python -m app.seed.seed_base --country SG \
    --company "Acme Pte Ltd" --admin-email owner@acme.com \
    --admin-name "Ann Owner" --admin-password 'a-temporary-password'

    seed_base applies the country pack and creates the first administrator, who must choose a new password at first sign-in. It is safe to run again; a second run adds only what is missing.

  5. Start it.

    docker compose up -d

    Open https://erp.yourcompany.com and sign in as the administrator.

  6. Install the licence under Setup › Plan & Licence. See installing a licence.

  7. Set up backups before anyone enters real data: Backups.

Checking it is healthy

https://erp.yourcompany.com/api/health answers {"status": "ok", ...} with the running version. Point your monitoring at it. docker compose ps should show every container running and the backend healthy; docker compose logs backend and docker compose logs jobs show what they are doing.

Security checklist

  • Only ports 80, 443 and your SSH port open; SSH by key only.
  • Automatic security updates on the host (unattended-upgrades).
  • .env mode 600 and out of any repository.
  • The administrator's temporary password changed at first sign-in (the system insists).
  • Backups encrypted, copied off the server, and a restore tried.

The application refuses to start with settings that would be unsafe in production, such as a missing SECRET_KEY, and says which.

Getting help

Self-hosted licences include support by email at support@consoletium.com. Include the version from /api/health and the last lines of docker compose logs backend.