MidnightDocs

Install the server#

Prepare a single Linux VM and install the Midnight package. This gets you to a first boot that is ready for a deploy; it does not itself prove a deploy.

Before you start#

Prepare the host first. Each item below is a real prerequisite, not a recommendation.

Requirement Detail
Operating system Ubuntu 24.04 or Debian 12, single VM, with systemd and journalctl
Access Root or sudo
Cgroups v2 unified hierarchy
Docker Upstream docker-ce or compatible, API v1.43 or newer. The distribution docker.io package is not supported
Docker configuration /etc/docker/daemon.json absent, or mergeable with the Midnight baseline
Ports 80 and 443 free, or already reserved by your Traefik service
Firewall Mode known and configured to allow the intended public route
Mandatory access control AppArmor or SELinux state reviewed
Time and naming Clock synchronised, resolvable FQDN set
Postgres Reachable from the host, with a database and role prepared
Traefik Installed by you, with static file-provider configuration pointing at the Midnight dynamic directory
External binaries buildkitd, buildctl and registry installed or planned, pinned
Important

Traefik and Postgres are yours to run. Midnight routes through a Traefik you operate and stores state in a Postgres you provide. Neither is installed for you.

What the package does#

Installing the Debian package:

  • creates the midnight system user and group;
  • installs default configuration when none is present;
  • generates independent cursor, credential-MAC, variable-intent and variable-encryption keys when needed;
  • runs available migrations when a connection string is configured;
  • writes a post-install doctor report to /var/lib/midnight/doctor-postinst.json; and
  • runs systemctl daemon-reload.

It installs assets under /etc/midnight, /var/lib/midnight, /var/log/midnight, /run/midnight and /usr/lib/systemd/system, and provides six units:

midnight-server, midnight-worker, midnight-agent, midnight-buildkit, midnight-buildkit-worker, midnight-registry.

Important

Enabling the services is a deliberate operator step after validation. Installation does not start them.

Install and validate#

  1. Install the package on the prepared host.

  2. Read the post-install doctor report:

    cat /var/lib/midnight/doctor-postinst.json

  3. Resolve anything the report flags before enabling units.

  4. Enable and start the units once the report is clean.

  5. Check unit state and logs:

    systemctl status midnight-server
    journalctl -u midnight-server -n 200

Verify#

  • The doctor report shows no unresolved findings.
  • All six units are active.
  • Migrations have run against your Postgres database.
  • Traefik's file provider is reading the Midnight dynamic directory.

If it does not work#

Symptom Check Recovery
Docker-related failures Whether docker.io is installed instead of docker-ce The distribution package is not supported; install upstream Docker
Docker API errors The Docker API version v1.43 or newer is required
Migrations did not run Whether a connection string was configured at install time Configure it and run the available migrations
Ports unavailable What already holds 80 and 443 Free them, or point Midnight at your existing Traefik
Routing never works Traefik's static configuration The file provider must point at the Midnight dynamic directory
Units fail immediately after enabling journalctl -u <unit> Resolve the doctor findings before enabling, not after

Next#