Skip to content

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):

yaml
# 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-stopped

PORTUNUS_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:

bash
openssl genpkey -algorithm ed25519 -out portunus-signing.pem
bash
openssl 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.

bash
docker compose up -d

Then 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 ​

TagWhat it is
latest, vX.Y.Z, vX.YReleases
mainThe current main branch
nightlyScheduled 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 ​

bash
git clone https://github.com/ralphv/portunus.git
cd portunus
docker build -t portunus:latest .
# or: npm run docker:build

To run on a remote server, export the image and load it there:

bash
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 -d

After it's running ​

  1. Put it behind HTTPS and set AUTH_URL to the public origin. See Running over HTTPS.
  2. Sign in with Google and create a vault. Save the recovery code and the portunus.key keyfile. 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) ​

bash
npm install
npm run dev          # dev server on http://localhost:3000 (needs .env.local)

See CONTRIBUTING.md for the full development setup.