The postal command
Reference for the postal helper command installed from the postalserver/install repository.
The postal command used throughout these docs is a small Bash script from the installation helper repository, which the pre-requisites page has you clone to /opt/postal/install and symlink to /usr/bin/postal. It wraps Docker Compose so that you don't need to remember the container commands.
All commands operate on a docker-compose.yml in /opt/postal/install, which is generated for you from a template (templates/docker-compose.v3.yml) the first time you run bootstrap, upgrade or any command that needs it. Docker Compose is run with the project name postal, so the containers are named postal-web-1, postal-smtp-1, postal-worker-1 and so on.
Running Postal
| Command | Description |
|---|---|
postal start | Start all services in the background (docker compose up -d). Extra arguments are passed through, e.g. postal start web. |
postal stop | Stop and remove the containers (docker compose down). |
postal restart | Restart all containers. Required after changing postal.yml. |
postal status | Show the running containers (docker compose ps). |
postal logs [service] | Show logs for all services or one of web, smtp, worker. Extra arguments are passed through, e.g. postal logs -f worker. |
postal bash [service] | Open a shell inside a running service container. |
postal dc [args] | Run any other docker compose command against the Postal project, e.g. postal dc pull. |
Setup and upgrade
| Command | Description |
|---|---|
postal bootstrap hostname [path] | Create initial configuration in path (default /opt/postal/config): postal.yml from the example file with your hostname and a random rails.secret_key filled in, a Caddyfile, and a 1024-bit RSA signing.key. Existing files are never overwritten. Also generates docker-compose.yml for the latest release. |
postal initialize | Pull the image and run postal initialize inside a temporary container to create the main database and load the schema. |
postal upgrade [version] | Upgrade to the given version (or the latest release). See Upgrading. |
postal upgrade-db | Run database migrations only, without pulling a new image or restarting. Useful after restoring a database from another installation. |
postal set-version x.x.x | Regenerate docker-compose.yml for a specific version without pulling or restarting anything. |
Other tools
These run the corresponding command from the container image in a temporary runner container.
| Command | Description |
|---|---|
postal make-user | Interactively create a global administrator user (prompts for e-mail address, first name, last name and password). |
postal default-dkim-record | Print the DKIM TXT record to publish at postal._domainkey.{return path domain}. |
postal test-app-smtp address | Send a test e-mail using the smtp section of your configuration. |
postal console | Open a Rails console against your installation. |
postal version | Print the version of Postal in the configured image. |
Options
| Option | Description |
|---|---|
--version x.x.x | With bootstrap or upgrade, use this version instead of looking up the latest release on GitHub. |
--no-git-pull | With upgrade, skip updating the helper repository first. |
--dev | Print the commands that would be run instead of running them. |
Looking up the latest release requires curl and jq and makes an unauthenticated request to the GitHub API, which is rate limited. If you hit the limit, pass an explicit version.
Customising the installation
Number of workers
To run more than one worker container, add a docker-compose.override.yml (see below) that sets the number of replicas for the worker service. This survives upgrades, whereas postal start --scale worker=3 is reset to one worker the next time postal upgrade runs.
services:
worker:
deploy:
replicas: 3
Overriding the compose file
Docker Compose automatically merges docker-compose.override.yml from the same directory. Use this for changes such as log drivers, extra environment variables or resource limits, so that they survive upgrades (the generated docker-compose.yml is replaced on every upgrade).