dpndncY

Deploying on one Linux machine

For a virtual machine, a bare-metal server or a cloud instance (EC2, Azure VM, Compute Engine, and so on). It installs Docker, writes the configuration and starts the platform with HTTPS. Read Deploying dpndncY for the model.

#What you need

  • A 64-bit Linux machine with 2 vCPU, 4 GB of memory and 20 GB of disk or more. Debian, Ubuntu, RHEL and compatible systems work; the installer relies on Docker's own installer for the rest.
  • root access (sudo).
  • Two DNS names pointing at the machine, for example dpndncy.example.com and api.dpndncy.example.com.
  • Inbound ports 80 and 443 (and 22 for you). Nothing else needs to be open.
  • Outbound HTTPS, unless the site is air-gapped (Running dpndncY without internet access (air-gapped)).

#Install

curl -fsSL https://dpndncy.com/install.sh \
  | sudo bash -s -- --domain dpndncy.example.com --email [email protected]

Or from the files you were given (put dpndncy-deploy.tar.gz next to install.sh, and nothing is downloaded; load the image first with docker load if the machine has no registry access, see Getting the software):

sudo bash install.sh --domain dpndncy.example.com --email [email protected] --version 2.9.0

The script:

  1. installs Docker Engine and the Compose plugin if they are missing;
  2. puts the deployment files in /opt/dpndncy;
  3. writes /opt/dpndncy/.env with a generated APP_SECRET and a generated first operator password (shown once at the end of the run, readable only by root);
  4. starts the stack, waits for it to be healthy, and prints the two addresses.

Then open https://dpndncy.example.com, sign in with the operator account the script printed, and continue with "Setting up a new workplace" in Deploying dpndncY. Set ENABLE_BOOTSTRAP_SUPERADMIN=false in /opt/dpndncy/.env afterwards and run docker compose up -d in that directory.

#Options

Option Meaning
--domain NAME console hostname (required)
--api-domain NAME API hostname. Default: api. plus the domain
--email ADDRESS first operator account, and the address Let's Encrypt writes to
--internal-tls use Caddy's internal certificate authority, for a network with no public DNS
--version TAG image version. Default stable. Use 2.9.0 to pin
--dir PATH where the configuration lives. Default /opt/dpndncy

Running the script again is safe. It keeps your .env and your data, pulls the image again and restarts what changed.

#Try it first without a domain

sudo bash deploy/install.sh --quick

This runs one container over plain HTTP on ports 8080 (console) and 8081 (API) of the machine's address. It is for evaluation only: no HTTPS, and the session cookie is sent unencrypted.

#Doing it by hand

If you do not want the script: install Docker, then follow Deploying with Docker. The script does nothing else.

#After a reboot

The containers restart by themselves (restart: unless-stopped) and Docker starts at boot. Nothing else is needed.

#Day-to-day

cd /opt/dpndncy
docker compose ps                 # status
docker compose logs -f dpndncY    # application log
docker compose pull && docker compose up -d     # update to the current image of your tag

Backups and upgrades are in Running dpndncY.

#Pre-built machine image

deploy/packer builds an AMI or a qcow2 image with Docker and the container image already in it. On first boot each machine runs the installer once, so every machine generates its own secrets and none are baked into the image. The templates and their notes are in the deploy/packer folder.

#Troubleshooting

See the table at the end of Deploying with Docker. Two that are specific to a new machine:

Symptom Fix
The browser says the certificate is invalid Certificates are issued on first contact. Wait a minute and check docker compose logs caddy. Both names must resolve to this machine and ports 80 and 443 must be open
install.sh stops with "Could not pull" The machine cannot reach ghcr.io. Load the image from a file with docker load and run the script again; it accepts an image that is already present
← Previous
Ports and networking
Next →
Docker