Deploy Ackify in 5 Minutes with Docker Compose

Ackify is designed for simple deployment. This guide walks you through installation to production with automatic HTTPS.

Prerequisites

• A Linux server (Ubuntu 22.04 recommended)
• Docker and Docker Compose installed
• A domain name pointing to your server
• An OAuth2 account (Google, GitHub, or GitLab)

Step 1: Clone the repository

git clone https://github.com/btouchard/ackify-ce.git
cd ackify-ce

Step 2: Configure environment variables

Copy the example file and edit it:

cp .env.example .env
nano .env

Required variables:

# Public URL of your instance
APP_BASE_URL="https://ackify.your-domain.com"

# Database
DB_DSN="postgres://ackify:your-password@postgres:5432/ackify?sslmode=disable"

# OAuth2 (example with Google)
OAUTH_PROVIDER="google"
OAUTH_CLIENT_ID="your-client-id.apps.googleusercontent.com"
OAUTH_CLIENT_SECRET="your-client-secret"
OAUTH_COOKIE_SECRET="$(openssl rand -base64 32)"

# Optional: restrict to your domain's emails
OAUTH_ALLOWED_DOMAIN="@your-company.com"

Step 3: Configure OAuth2

Google

1. Go to the Google Cloud Console
2. Create a project or select an existing one
3. APIs & Services → Credentials → Create Credentials → OAuth Client ID
4. Type: Web application
5. Authorized redirect URIs: https://ackify.your-domain.com/oauth2/callback
6. Copy Client ID and Client Secret to .env

GitHub

1. Go to GitHub Developer Settings
2. OAuth Apps → New OAuth App
3. Authorization callback URL: https://ackify.your-domain.com/oauth2/callback
4. Copy Client ID and Client Secret
5. In .env: OAUTH_PROVIDER="github"

GitLab

1. In your GitLab instance: Admin → Applications
2. Redirect URI: https://ackify.your-domain.com/oauth2/callback
3. Scopes: read_user
4. In .env:

   OAUTH_PROVIDER="gitlab"
   OAUTH_GITLAB_URL="https://gitlab.your-company.com"
   

Step 4: Generate the Ed25519 key

This key is used to cryptographically sign confirmations:

openssl genpkey -algorithm Ed25519 -out ed25519.pem
cat ed25519.pem | base64 -w 0

Add the result to .env:

ED25519_PRIVATE_KEY_B64="your-base64-key"

Important: keep a secure backup of this key. Losing it would invalidate verification of existing signatures.

Step 5: Start the services

docker compose up -d

Verify everything is working:

docker compose ps
docker compose logs -f ackapp

Step 6: Configure Traefik (HTTPS)

If you're using Traefik as a reverse proxy, add labels to docker-compose.yml:

services:
  ackapp:
    image: btouchard/ackify-ce:latest
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.ackify.rule=Host(`ackify.your-domain.com`)"
      - "traefik.http.routers.ackify.entrypoints=websecure"
      - "traefik.http.routers.ackify.tls.certresolver=letsencrypt"

Step 7: Test the installation

# Health check
curl https://ackify.your-domain.com/healthz

# Signature page
open https://ackify.your-domain.com/sign?doc=test

Authenticate via OAuth2 and confirm reading of the "test" document.

Advanced configuration

SMTP for reminders

SMTP_HOST="smtp.your-provider.com"
SMTP_PORT="587"
SMTP_USER="notifications@your-domain.com"
SMTP_PASSWORD="your-password"
SMTP_FROM="Ackify <notifications@your-domain.com>"

Custom OAuth2 provider

For enterprise SSO (Keycloak, Auth0, etc.):

OAUTH_PROVIDER=""  # Leave empty
OAUTH_AUTH_URL="https://sso.company.com/oauth/authorize"
OAUTH_TOKEN_URL="https://sso.company.com/oauth/token"
OAUTH_USERINFO_URL="https://sso.company.com/userinfo"
OAUTH_SCOPES="openid,email,profile"

External PostgreSQL

To use an existing PostgreSQL database:

DB_DSN="postgres://user:pass@db.company.com:5432/ackify?sslmode=require"

And comment out the postgres service in docker-compose.yml.

Updates

docker compose pull
docker compose up -d

Database migrations run automatically on startup.

Troubleshooting

OAuth2 "redirect_uri_mismatch" error

Verify that the callback URL in your OAuth2 provider exactly matches APP_BASE_URL/oauth2/callback.

PostgreSQL connection error

Wait a few seconds for PostgreSQL to start, then restart:

docker compose restart ackapp

Detailed logs

docker compose logs -f ackapp

Conclusion

In 5 minutes, you have a working Ackify instance with HTTPS. Your teams can start confirming reading of your internal documents.

➡️ Full documentation — to go further.