ackify/docs/en/configuration.md

Configuration

Complete configuration guide for Ackify via environment variables.

Required Variables

These variables are required to start Ackify:

# Public URL of your instance (used for OAuth callbacks)
APP_DNS=sign.your-domain.com
ACKIFY_BASE_URL=https://sign.your-domain.com

# Your organization name (displayed in the interface)
ACKIFY_ORGANISATION="Your Organization Name"

# PostgreSQL configuration
POSTGRES_USER=ackifyr
POSTGRES_PASSWORD=your_secure_password
POSTGRES_DB=ackify

# OAuth2 Provider
ACKIFY_OAUTH_PROVIDER=google  # or github, gitlab, or empty for custom
ACKIFY_OAUTH_CLIENT_ID=your_oauth_client_id
ACKIFY_OAUTH_CLIENT_SECRET=your_oauth_client_secret

# Secret to encrypt session cookies (generate with: openssl rand -base64 32)
ACKIFY_OAUTH_COOKIE_SECRET=your_base64_encoded_secret_key

Optional Variables

Server

# HTTP listening address (default: :8080)
ACKIFY_LISTEN_ADDR=:8080

# Log level: debug, info, warn, error (default: info)
ACKIFY_LOG_LEVEL=info

Security & OAuth2

# Restrict access to a specific email domain
ACKIFY_OAUTH_ALLOWED_DOMAIN=@company.com

# Enable silent auto-login (default: false)
ACKIFY_OAUTH_AUTO_LOGIN=false

# Custom logout URL (optional)
ACKIFY_OAUTH_LOGOUT_URL=https://your-provider.com/logout

# Custom OAuth2 scopes (default: openid,email,profile)
ACKIFY_OAUTH_SCOPES=openid,email,profile

Authentication Methods

Important: At least ONE authentication method must be enabled (OAuth or MagicLink).

# Force enable/disable OAuth (default: auto-detected from credentials)
ACKIFY_AUTH_OAUTH_ENABLED=true

# Enable MagicLink passwordless authentication (default: false)
# Requires ACKIFY_MAIL_HOST to be configured
ACKIFY_AUTH_MAGICLINK_ENABLED=true

Auto-detection:

• OAuth is automatically enabled if ACKIFY_OAUTH_CLIENT_ID and ACKIFY_OAUTH_CLIENT_SECRET are set
• MagicLink requires explicit activation with ACKIFY_AUTH_MAGICLINK_ENABLED=true + SMTP configuration
• SMTP/Email service is automatically enabled when ACKIFY_MAIL_HOST is configured (independent of MagicLink)

Note: SMTP and MagicLink are two distinct features:

• SMTP = Email reminder service for expected signers (auto-detected)
• MagicLink = Passwordless email authentication (requires explicit activation + SMTP)

Administration

# Admin email list (comma-separated)
ACKIFY_ADMIN_EMAILS=admin@company.com,admin2@company.com

# Restrict document creation to admins only (default: false)
ACKIFY_ONLY_ADMIN_CAN_CREATE=false

Admins have access to:

• Admin dashboard (/admin)
• Document metadata management
• Expected signers tracking
• Email reminders sending
• Document deletion

When ACKIFY_ONLY_ADMIN_CAN_CREATE is enabled:

• ✅ Only admin users can create new documents
• ✅ Non-admin users will see an error message when attempting to create documents
• ✅ Both API endpoints (POST /documents and GET /documents/find-or-create) are protected

Rate Limiting

Configure API rate limits to prevent abuse and control request rates:

# Magic Link authentication rate limits (per time window)
ACKIFY_AUTH_MAGICLINK_RATE_LIMIT_EMAIL=3   # Max requests per email (default: 3)
ACKIFY_AUTH_MAGICLINK_RATE_LIMIT_IP=10     # Max requests per IP (default: 10)

# General API rate limits (requests per minute)
ACKIFY_AUTH_RATE_LIMIT=5          # Authentication endpoints (default: 5/min)
ACKIFY_DOCUMENT_RATE_LIMIT=10     # Document creation (default: 10/min)
ACKIFY_GENERAL_RATE_LIMIT=100     # General API requests (default: 100/min)

# CSV Import
ACKIFY_IMPORT_MAX_SIGNERS=500     # Max signers per CSV import (default: 500)

When to adjust:

• Testing/CI: Increase limits (e.g., 1000) to prevent 429 errors during automated tests
• High traffic: Increase GENERAL_RATE_LIMIT for production workloads
• Security: Lower AUTH_RATE_LIMIT to prevent brute-force attacks

Logging

# Log level: debug, info, warn, error (default: info)
ACKIFY_LOG_LEVEL=info

# Log format: classic or json (default: classic)
ACKIFY_LOG_FORMAT=classic

Log formats:

• classic: Human-readable format for development and simple deployments
• json: Structured JSON for log aggregators (Datadog, ELK, Splunk)

Example JSON output:

{"time":"2025-11-24T10:00:00Z","level":"INFO","msg":"Server started","port":8080}

Document Checksum (Optional)

Configuration for automatic checksum computation when creating documents from URLs:

# Maximum file size to download for checksum calculation (default: 10485760 = 10MB)
ACKIFY_CHECKSUM_MAX_BYTES=10485760

# Timeout for checksum download in milliseconds (default: 5000ms = 5s)
ACKIFY_CHECKSUM_TIMEOUT_MS=5000

# Maximum number of HTTP redirects to follow (default: 3)
ACKIFY_CHECKSUM_MAX_REDIRECTS=3

# Comma-separated list of allowed MIME types (default includes PDF, images, Office docs, ODF)
ACKIFY_CHECKSUM_ALLOWED_TYPES=application/pdf,image/*,application/msword,application/vnd.openxmlformats-officedocument.wordprocessingml.document,application/vnd.ms-excel,application/vnd.openxmlformats-officedocument.spreadsheetml.sheet,application/vnd.oasis.opendocument.*

Note: These settings only apply when admins create documents via the admin dashboard with a remote URL. The system will attempt to download and calculate the SHA-256 checksum automatically.

Testing variables (⚠️ NEVER use in production):

# Disable SSRF protection (testing only)
ACKIFY_CHECKSUM_SKIP_SSRF_CHECK=false

# Skip TLS certificate verification (testing only)
ACKIFY_CHECKSUM_INSECURE_SKIP_VERIFY=false

These variables disable critical security protections and should only be used in isolated test environments.

Row Level Security (RLS)

Ackify uses PostgreSQL Row Level Security for tenant data isolation. This is configured automatically during migrations.

# Password for the ackify_app database role (required for RLS)
ACKIFY_APP_PASSWORD=your_secure_app_password

How it works:

• The migrate tool creates a non-superuser role ackify_app before running migrations
• The application connects to PostgreSQL using this role
• RLS policies automatically filter all queries by tenant
• No data leakage possible even if application code forgets tenant filtering

See Row Level Security for detailed documentation.

Advanced Configuration

OAuth2 Providers

See OAuth Providers for detailed configuration of:

• Google OAuth2
• GitHub OAuth2
• GitLab OAuth2 (public + self-hosted)
• Custom OAuth2 provider

Email (SMTP)

See Email Setup to configure email reminders sending.

Complete Example

Example .env for a production installation:

# Application
APP_DNS=sign.company.com
ACKIFY_BASE_URL=https://sign.company.com
ACKIFY_ORGANISATION="ACME Corporation"
ACKIFY_LOG_LEVEL=info
ACKIFY_LISTEN_ADDR=:8080

# Database
POSTGRES_USER=postgres
POSTGRES_PASSWORD=super_secure_password_123
POSTGRES_DB=ackify

# RLS (Row Level Security)
ACKIFY_APP_PASSWORD=another_secure_password_456

# OAuth2 (Google)
ACKIFY_OAUTH_PROVIDER=google
ACKIFY_OAUTH_CLIENT_ID=123456789-abc.apps.googleusercontent.com
ACKIFY_OAUTH_CLIENT_SECRET=GOCSPX-xyz123
ACKIFY_OAUTH_ALLOWED_DOMAIN=@company.com

# Security
ACKIFY_OAUTH_COOKIE_SECRET=ZXhhbXBsZV9iYXNlNjRfc2VjcmV0X2tleQ==

# Administration
ACKIFY_ADMIN_EMAILS=admin@company.com,cto@company.com

# Email (optional - omit MAIL_HOST to disable)
ACKIFY_MAIL_HOST=smtp.gmail.com
ACKIFY_MAIL_PORT=587
ACKIFY_MAIL_USERNAME=noreply@company.com
ACKIFY_MAIL_PASSWORD=app_specific_password
ACKIFY_MAIL_FROM=noreply@company.com
ACKIFY_MAIL_FROM_NAME="Ackify - ACME"
ACKIFY_MAIL_TEMPLATE_DIR=templates/emails
ACKIFY_MAIL_DEFAULT_LOCALE=en

# Document Checksum (optional - for auto-checksum from URLs)
ACKIFY_CHECKSUM_MAX_BYTES=10485760
ACKIFY_CHECKSUM_TIMEOUT_MS=5000
ACKIFY_CHECKSUM_MAX_REDIRECTS=3

Configuration Validation

After modifying .env, restart:

docker compose restart ackify-ce

Check logs:

docker compose logs -f ackify-ce

Test the health check:

curl http://localhost:8080/api/v1/health

Production Variables

Production security checklist:

• ✅ Use HTTPS (ACKIFY_BASE_URL=https://...)
• ✅ Generate strong secrets (64+ characters)
• ✅ Configure RLS with strong password (ACKIFY_APP_PASSWORD)
• ✅ Restrict OAuth domain (ACKIFY_OAUTH_ALLOWED_DOMAIN)
• ✅ Configure admin emails (ACKIFY_ADMIN_EMAILS)
• ✅ Use PostgreSQL with SSL in production
• ✅ Log in info mode (not debug)
• ✅ Regularly backup the database

See Deployment for more details on production deployment.