Run Postern under Docker on a machine you own, then open its Console.
Before you start
Docker.Install Docker first. It is the only thing
you install by hand.
A machine that stays on. While it is off, your agents reach nothing. Keep it updated, the
same as anything else you run.
About 10 minutes, plus the time the image takes to download.
Somewhere to keep one password. You create it in step 2. Postern’s database
never accepts a different one afterwards, so open your password manager now.
Windows: not tested. Postern runs under Docker, so Windows should work. Nobody has run it
there. Treat every Windows line on this page as untested.
another computer — a NAS, a spare machine, a computer with no screen
Sign in to that computer over SSH. Run steps 1 to 3 there, then forward the Console port in step 4.
Postern runs either way. A NAS or a spare machine works the same as the computer in front of you.
The second path needs SSH on that computer, and nothing else changes.
1
Get the compose file
Open a terminal on the machine that will run Postern. On macOS, press Command-Space, type
Terminal, press Return. On Windows, press the Windows key, type PowerShell, press
Return.Make a folder and download the one file Postern needs:
mkdir postern && cd posterncurl -O https://raw.githubusercontent.com/getpostern/postern/main/docker-compose.yml
On Windows, type curl.exe — in PowerShell, curl means something else. Nobody has tested these
lines:
mkdir postern; cd posterncurl.exe -O https://raw.githubusercontent.com/getpostern/postern/main/docker-compose.yml
The folder now holds one file, docker-compose.yml. Every command below runs from this folder.You can clone the whole repository instead, if you have Git:
git clone https://github.com/getpostern/postern.git && cd postern. Postern needs nothing else
from it.
2
Write the database password
Postern’s database needs one password. It lives in a file named .env, beside
docker-compose.yml.
Postgres records this password the first time it starts. It never accepts a different one against
the same data, and there is no way to change it afterwards. Keep .env. Do not type the password
in front of docker compose up. That creates a new one on every run, and every other
docker compose command then fails.
In that folder, run the line for your system. It makes a password of letters and digits only. A
/, :, @, ?, #, & or + breaks the address Postern uses to reach its database. Postern
then exits at once. openssl rand -base64 32 is not a substitute: its output holds those characters
often.
.env now holds one line: POSTGRES_PASSWORD= and 48 letters and digits. That is the whole of
Postern’s required configuration. Every other setting has a working default.Copy that line into your password manager now. The leading dot makes .env invisible in Finder and
File Explorer. Do not make .env in Notepad — Notepad adds .txt to the name.
3
Start Postern
Docker must be open first. On macOS and Windows, open the Docker Desktop application and wait
for it to finish its own start-up. On Linux, Docker runs as a service and needs nothing opened.From the folder that holds docker-compose.yml, start Postern:
docker compose up -d
The first run downloads the image ghcr.io/getpostern/postern, so it takes minutes. Later runs take
seconds. The image runs on Intel and AMD machines, and on ARM machines such as Apple Silicon.
Postern sets up its database tables before it answers anything, so port 8787 stays quiet for a few
seconds after the command returns.Postern opens two ports to this computer only: 8787, the Console port, and 8788, the agent
port. Only this computer can reach these addresses. Nothing on your Wi-Fi, and nothing on the
internet, can. The database gets no port at all. Only Postern reaches it, over the private network
Docker Compose creates.
If another program already holds 8787 or 8788, the app container does not start. Add a line to
.env, below the password line:
REST_PORT=8790
Then run docker compose up -d again. The Console now answers at http://localhost:8790, and
every 8787 below becomes 8790. MCP_HTTP_PORT moves the agent port the same way. If you
already connected Google, Microsoft or
WHOOP, change the address you registered there to the new port. They match it
exactly, character for character.
Docker keeps two storage areas outside the containers: your data, and the key that unlocks every
account you connect. docker compose down -v deletes both, permanently. Every account you
connected becomes unreadable, and nothing can recover them. docker compose down without -v is
safe: it removes the containers and leaves both storage areas alone.Take a copy of the key: Back up, export and erase. If Postern cannot
open the vault at start-up, it refuses to start rather than starting broken. A database restored
without its key stops there.
The VAULT KEY IS NOT BACKED UP notice. Postern prints it in its own log at every start. It
is a reminder, not an error, and Postern runs anyway. It appears while Postern holds the key
itself and no marker file sits beside it.The notice tells you to acknowledge the copy in the Console. No such control ships. Nothing in
the Console writes that marker, and no address answers it. So the notice still appears after you
hold a good copy.Two things stop it. Take your copy of the key first, then choose one.
Write the marker yourself. Postern looks for a file named master.key.backed-up beside the
key. From the folder that holds docker-compose.yml:
Postern checks that the file is there. It never reads what is in it. Write the date anyway. It
tells a later you when you took the copy.
Hold the key yourself. Put PCI_MASTER_KEY in .env — a base64 32-byte key you keep —
and restart. Make one with openssl rand -base64 32. Set it before the first start. A new key
against accounts encrypted under an old one makes Postern refuse to start.
A restore brings the notice back. The marker sat in the old storage area, and the restore makes a
new one.
Four commands cover the first week. Run them from the same folder:
docker compose ps # is it updocker compose logs -f app # read its logdocker compose stop # pause it; docker compose start resumesdocker compose pull && docker compose up -d # move to a newer image
To hold one release instead of the newest, add POSTERN_VERSION=v0.1.0 to .env.
4
Open the Console
The Console answers at http://localhost:8787, and only on the machine Postern runs on.If Postern runs on the computer in front of you, open
http://localhost:8787.If Postern runs on another computer, forward the Console port to your own computer. Run this on
your own computer, not on the machine Postern runs on. Turn on SSH on that machine first.
Replace YOUR_MACHINE with however you normally reach that computer: a name, a user@host, or an
IP address. The terminal then prints nothing and does not return to a prompt. That is the command at
work, not a hang. Leave that window open, use a second terminal window for anything else, and press
Control-C when you want to stop. Now open http://localhost:8787 on your
own computer.Anyone who can reach the Console port can change your settings and create agent keys. It has no
password, so it stays on this computer. Do not change the address in docker-compose.yml to your
network. Do not put a tunnel service in front of it. The full argument is in
The Console has no authentication.The Console opens on a page headed Your gate is new. with one button, Add your first source.
The left sidebar lists Gatehouse, then the six sectors, then Sources, Agents & keys,
The ledger and Settings. A sector is one area of your life: finance, mail, calendar,
contacts, health, home. It is the smallest thing you can grant.
The Console on a fresh install. The one button reads Add your first source.
To let an agent reach Postern from another device, see Remote access. It is
off by default, and it never moves the Console off this machine.
docker compose up -d stops at once and prints set POSTGRES_PASSWORD in .env — generate one with: openssl rand -hex 24
.env is missing or empty. Run the step 2 command again, in the folder that holds docker-compose.yml.
app starts and exits within seconds, and your password holds a character that is not a letter or a digit
Run the step 2 command again, then docker compose down -v && docker compose up -d. That wipes the database, which is safe only before you connect anything.
db is up, app cannot sign in to the database, and .env changed since the first start
Postgres kept the first password. Put the original line back in .env, then run docker compose up -d.
app does not start, and another program on this computer already uses 8787 or 8788
Move Postern’s port. Step 3 carries the line to add.
The browser shows a not-found page while curl -s localhost:8787/healthz still answers {"status":"ok"}
Postern runs, and its Console files are not where it looked. Run docker compose logs app; the log names the folder it tried. Set PCI_CONSOLE_DIR in .env to the right folder.
The log prints VAULT KEY IS NOT BACKED UP at every start
That is the reminder, not a fault. Step 3 has the two ways to stop it.
Postern runs on a machine you own. Docker downloaded a finished image from
ghcr.io/getpostern/postern and built nothing on that machine. There is no Postern account and no
Postern server in the middle. You have connected nothing yet, and no agent can reach anything until
you grant it.Three things are now yours to keep: the machine, on and updated; the one line in .env; and a copy
of the vault key.
