Skip to content

deploy-docker.md

Latest commit

 

History

History
95 lines (64 loc) · 2.4 KB

deploy-docker.md

File metadata and controls

95 lines (64 loc) · 2.4 KB
Raw

Docker Deployment Guide

Security: Always use HTTPS in production. Terminate TLS at a reverse proxy (nginx, ALB, Caddy) in front of the Vault service. See SECURITY.md for the full production hardening checklist.

This project is ready to run as a Dockerized service.

Current Image Publishing Status

Initial release (0.1.0) is assumed already shipped. Use 0.1.1+ for subsequent tags.

Server releases publish Docker images to GHCR via: release-by-tag.yml

Image name format:

  • ghcr.io/<github-owner-lowercase>/oauth-vault:<version>
  • ghcr.io/<github-owner-lowercase>/oauth-vault:latest

Release trigger:

  • Push tag: server/vX.Y.Z

Required Runtime Environment

You must set:

  • OAUTH_VAULT_DATABASE_URL
  • OAUTH_VAULT_ENCRYPTION_KEYS
  • OAUTH_VAULT_API_KEYS (or JWT-mode variables if using JWT auth)
  • OAUTH_VAULT_CALLBACK_BASE_URL
  • OAUTH_VAULT_CALLBACK_PATH

Recommended:

  • OAUTH_VAULT_AUTH_MODE=jwt for production
  • OAUTH_VAULT_REFRESH_POLL_SECONDS
  • OAUTH_VAULT_REFRESH_LEAD_SECONDS

Database Bootstrapping

Vault expects schema to exist when OAUTH_VAULT_AUTO_CREATE_SCHEMA=false (default).

Use one of:

  1. New Postgres instance initialized with: migrations/001_init.sql

  2. Existing Postgres: run migration SQL once before starting Vault.

The image now includes migration files at: /app/migrations/001_init.sql

Minimal docker run Example

docker run -d --name oauth-vault \
  -p 8090:8090 \
  -e OAUTH_VAULT_DATABASE_URL='postgresql+asyncpg://postgres:postgres@db:5432/oauth_vault' \
  -e OAUTH_VAULT_ENCRYPTION_KEYS='REPLACE_WITH_FERNET_KEY' \
  -e OAUTH_VAULT_API_KEYS='REPLACE_WITH_STRONG_KEY' \
  -e OAUTH_VAULT_CALLBACK_BASE_URL='https://vault.example.com' \
  -e OAUTH_VAULT_CALLBACK_PATH='/v1/oauth/callback' \
  ghcr.io/<owner>/oauth-vault:<version>

Health check:

curl -fsS http://localhost:8090/health

Compose-Based Deployment

For first-time local/hosted setup, this repo's docker-compose.yml already wires:

  • Postgres
  • Vault service
  • Automatic initial schema load via migrations/001_init.sql

Start:

docker compose up -d postgres oauth-vault

Release and Push Docker Image

From this repo:

make release-server VERSION=0.1.1
make release-server-push VERSION=0.1.1

This creates and pushes server/v0.1.1, which triggers GHCR publish.