Install
Portunus ships as a single Docker image, ghcr.io/ralphv/portunus. It's a Next.js standalone build that runs as non-root and has no database.
You need:
- Docker (or any OCI container runtime)
- A Google OAuth client. See Google OAuth setup; it takes about five minutes, once.
- HTTPS in front of the container for anything other than
localhost. See Running over HTTPS.
Want to look around first? The local demo needs none of this.
Docker Compose
Fill in the environment values (see Configuration):
# docker-compose.yml
services:
portunus:
image: ghcr.io/ralphv/portunus:latest
ports:
- "3000:3000"
environment:
AUTH_GOOGLE_ID: "your-google-client-id"
AUTH_GOOGLE_SECRET: "your-google-client-secret"
AUTH_SECRET: "generate-with-openssl-rand-hex-32"
AUTH_URL: "http://localhost:3000" # public origin when deployed
PORTUNUS_SIGNING_PRIVATE_KEY: "see-below"
restart: unless-stoppedPORTUNUS_SIGNING_PRIVATE_KEY is the Ed25519 key the server signs the Drive vault file with (Vault signatures); the server won't start without it. Generate one per deployment:
openssl genpkey -algorithm ed25519 -out portunus-signing.pemopenssl pkey -in portunus-signing.pem -outform DER | base64 | tr -d '\n'Put the one-line output in PORTUNUS_SIGNING_PRIVATE_KEY and keep portunus-signing.pem somewhere safe: vaults signed with a key can only be verified with that same key.
docker compose up -dThen open http://localhost:3000.
Keep secrets out of git
If you keep this compose file in a git repo, don't commit the real secret values. Track a placeholder version, or use env_file: .env (gitignored) instead.
Image tags
| Tag | What it is |
|---|---|
latest, vX.Y.Z, vX.Y | Releases |
main | The current main branch |
nightly | Scheduled daily build |
sha-<short> | A specific commit |
pr-<N> | The latest build of pull request #N, for testing it before it's merged (not for production) |
Release images are signed with cosign. Self-host from a release you have verified. The security model explains why that matters.
Building the image yourself
git clone https://github.com/ralphv/portunus.git
cd portunus
docker build -t portunus:latest .
# or: npm run docker:buildTo run on a remote server, export the image and load it there:
docker save portunus:latest | gzip > portunus.tar.gz # or: npm run docker:save
# copy to the server, then:
gunzip -c portunus.tar.gz | docker load
docker compose up -dAfter it's running
- Put it behind HTTPS and set
AUTH_URLto the public origin. See Running over HTTPS. - Sign in with Google and create a vault. Save the recovery code and the
portunus.keykeyfile. The keyfile is per-device. If you lose every copy and the recovery code, the vault can't be recovered. There is no password reset.
Building from source (development)
npm install
npm run dev # dev server on http://localhost:3000 (needs .env.local)See CONTRIBUTING.md for the full development setup.
