Lord - Minimalist PaaS Management

Lord - Minimalist PaaS Management

expert knowledge of lord, an ultra-minimalist paas management cli tool for deploying docker containers to remote servers via ssh.

• lord allows a user to deploy and manage several standalone containers to a remote server.
• each container can expose a web service which is auto setup with https certs via traefik.
• when deploying via lord, a "direct push" model or a container registry model is supported for getting the container onto the remote server.
• lord also exposes cli commands for detroying the container, checking status, viewing logs, and system monitoring (see cli reference below).
• lord requires a few things in order to function, which are described in the "prerequisites" section.

the user may ask you to perform some lord actions via the cli tool, troubleshoot usage of lord, or verify/​modify the lord configuration for a given repo.

prerequisites

• the lord binary must be installed on the system. this can be done via github release download or make install from the repo (requires go to be installed)
• docker must be installed and running on the local machine (lord will auto install it on the remote server)
• A Dockerfile must be present in the base repository and follow the conventions described in "container conventions" below
• A lord.yml file must be present in the base repository (or a *.lord.yml invoked via -config flag) to tell lord what to do. this file may be created via the -init flag
• the local machine must have ssh access to the remote server specified in the lord config (the ssh keyfile can be specified in the lord config, otherwise the default for the system is used)

cli reference

lord -init         # create lord.yml configuration file (populated with dummy values)
lord -deploy       # build and deploy application
lord -logs         # stream container logs from server
lord -destroy      # remove deployed containers
lord -status       # check deployment status (basically remote docker ps)
lord -server       # run/​check server setup (includes reverse proxy)
lord -proxy        # run/​check reverse proxy setup only
lord -recover      # recover server with bad lord dependency install
lord -logdownload  # download full log file from server
lord -registry     # setup and authenticate to container registry on the server
lord -dozzle       # run dozzle ui locally connected to remote server via ssh (great for searching/​inspecting logs and all containers on the server)
lord -monitor      # check system load of the host

lord -config {config variant} {any command from above} # run lord with the specific config variant (config variant}.lord.yml when using multiple configs

configuration reference

projects require a lord.yml file:

# required
name: myapp
server: 192.168.1.100

# optional registry (omit for registry-less deployment)
registry: my.realregistry.com/​me
authfile: ./​config.json

# optional settings
email: [email protected]
platform: linux/​amd64
target: production
web: true
hostname: myapp.example.com
environmentfile: .env
buildargfile: build.args
hostenvironmentfile: host.env
user: ubuntu
sshkeyfile: /​path/​to/​private/​key

volumes:
  - /​host/​data:/​container/​data

# advanced web configuration
webadvancedconfig:
  # timeout settings (global traefik - affects all web apps!)
  readtimeout: 300        # seconds, 0 = unlimited
  writetimeout: 300       # seconds, 0 = unlimited
  idletimeout: 180        # seconds

  # buffering settings (per-service, safe)
  maxrequestbodybytes: 10485760
  maxresponsebodybytes: 10485760
  memrequestbodybytes: 1048576

container conventions

• web services must expose port 80 internally
• persistent data should use /​data volume mount
• additional volumes can be specified in config

multi-config support

use config.lord.yml naming and -config config flag for multiple deployment targets in one repo. this can be used when you need different configs for staging, prod, etc. or if there are separate services built from the same binary/​container, which can have different build args.

project/
├── Dockerfile
├── prod.lord.yml
└── staging.lord.yml

deploy with: lord -config prod -deploy

deployment flow

1. build docker container locally with specified platform
2. push to registry OR save/​transfer directly (registry-less)
3. ssh to target server and ensure docker/​traefik setup
4. if webadvancedconfig timeouts set and traefik running:
   • read existing traefik config from /​etc/​traefik/​traefik.yml
   • apply "maximum wins" logic: update timeouts only if new values are higher
   • restart traefik container if config updated
5. pull container and run with configured volumes/​settings
6. for web containers, configure traefik routing with optional buffering middleware

registry authentication

three methods supported:

method 1: username/​password file (simplest)

plain text file with username:password

registry: my.realregistry.com/​me
authfile: ./​registry-auth.txt

method 2: docker config file

json config copied to remote host's .docker/​config.json (overwrites entire file)

method 3: dynamic authentication

automatic authentication for:

• aws ecr: requires AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION
• digitalocean: requires DIGITALOCEAN_ACCESS_TOKEN

set via hostenvironmentfile in lord.yml

advanced web configuration

timeout settings (use with caution!)

affects global traefik reverse proxy serving all web containers on host:

• values in seconds
• 0 = unlimited
• "maximum wins" strategy across all deployments
• use for docker registries, large file uploads, long-polling apis

buffering settings (per-service, safe)

affects only the specific service:

• maxrequestbodybytes: max incoming request body size
• maxresponsebodybytes: max outgoing response body size
• memrequestbodybytes: threshold before buffering to disk

environment variables

• hostenvironmentfile: env vars on remote host during deployment (for registry auth, cloud credentials)
• environmentfile: env vars inside container at runtime

supported linux distributions

automatic docker installation on:

• ubuntu (apt)
• debian (apt)
• amazon linux 2023 (dnf)
• centos (yum)
• rhel (yum)

key design principles

• minimalism: minimal config options and dependencies
• simplicity: all you need is docker and ssh
• flexibility: deploy from pc or ci/​cd to any linux server
• single responsibility: one container per deployment, not orchestration
• automatic reverse proxy: traefik handles https certificates and routing
• registry optional: can deploy without a container registry