ackify-ce/install

Ackify CE - Installation Guide

This directory contains the installation scripts and configuration files for Ackify Community Edition.

Quick Start

Interactive Installation (Recommended)

The interactive installation script will guide you through the entire configuration process:

bash <(curl -fsSL https://raw.githubusercontent.com/btouchard/ackify-ce/main/install/install.sh)

The script will prompt you for:

1. Basic Configuration

   • Application Base URL (e.g., https://ackify.example.com)
   • Organization Name

2. OAuth2 Authentication (Optional)

   • Enable/disable OAuth
   • OAuth Provider (Google, GitHub, GitLab, or custom)
   • Client ID and Client Secret
   • Email domain restriction (optional)
   • Auto-login configuration (optional)

3. SMTP Configuration (Optional)

   • Enable/disable SMTP for email notifications
   • SMTP server settings (host, port, credentials)
   • Email sender configuration
   • TLS/STARTTLS settings

4. MagicLink Authentication (Optional)

   • Auto-enabled when SMTP is configured
   • Option to disable if needed

5. Admin Users (Required)

   • Configure at least one admin email address
   • Admins have access to document management and reminder features

6. Document Storage (Optional)

   • None (URL-only mode)
   • Local filesystem storage
   • S3-compatible storage (AWS, MinIO, Wasabi, etc.)

The script will automatically:

• Download the necessary configuration files (docker compose & .env.example)
• Generate secure secrets (cookie secret, Ed25519 key, database password)
• Create a ready-to-use .env file
• Validate that at least one authentication method is enabled

After Installation

1. Review the configuration:

   cd ackify-ce
   cat .env
   

2. Start Ackify:

   docker compose up -d
   

3. Check logs:

   docker compose logs -f ackify-ce
   

4. Access the application: Open your browser and navigate to the configured base URL

5. Verify health:

   curl http://localhost:8080/health
   

Manual Installation

If you prefer to configure manually:

1. Download configuration files:

   mkdir ackify-ce && cd ackify-ce
   curl -fsSL https://raw.githubusercontent.com/btouchard/ackify-ce/main/install/compose.yml -o compose.yml
   curl -fsSL https://raw.githubusercontent.com/btouchard/ackify-ce/main/install/.env.example -o .env
   

2. Generate secrets:

   # Cookie secret (for session encryption)
   openssl rand -base64 32
   
   # Ed25519 private key (for signatures)
   openssl rand 64 | base64 -w 0
   
   # Database password
   openssl rand -base64 24
   

3. Edit .env file:

   • Configure your application URL and organization name
   • Set up at least one authentication method (OAuth or MagicLink)
   • Add the generated secrets
   • Configure at least one admin user (required)
   • Configure optional features (SMTP for email reminders and MagicLink)

4. Start the application:

   docker compose up -d
   

Authentication Methods

Ackify CE supports two authentication methods. At least one must be enabled.

OAuth2 Authentication

OAuth allows users to sign in using existing accounts from popular providers.

Supported Providers:

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

Required Variables:

OAUTH_PROVIDER=google
OAUTH_CLIENT_ID=your_client_id
OAUTH_CLIENT_SECRET=your_client_secret

Setup Links:

• Google OAuth Setup
• GitHub OAuth Setup
• GitLab OAuth Setup

MagicLink Authentication

MagicLink provides passwordless authentication via email. Users receive a secure link to sign in.

Requirements:

• SMTP server configuration (MAIL_HOST must be set)

When to use:

• Simplified user experience (no password management)
• Internal applications where email domain is trusted
• Combination with OAuth for flexible authentication

Document Storage

Ackify CE can optionally store uploaded documents, allowing users to upload files directly instead of providing URLs.

Storage Options

None (Default):

• Users must provide document URLs
• No local storage required
• Simplest configuration

Local Storage:

• Documents stored on the server filesystem
• Uses Docker volume for persistence
• Best for single-server deployments

ACKIFY_STORAGE_TYPE=local
ACKIFY_STORAGE_LOCAL_PATH=/data/documents
ACKIFY_STORAGE_MAX_SIZE_MB=50

S3-Compatible Storage:

• Works with AWS S3, MinIO, Wasabi, DigitalOcean Spaces, etc.
• Best for scalable/distributed deployments
• Supports any S3-compatible provider

ACKIFY_STORAGE_TYPE=s3
ACKIFY_STORAGE_MAX_SIZE_MB=50
ACKIFY_STORAGE_S3_ENDPOINT=https://s3.amazonaws.com
ACKIFY_STORAGE_S3_BUCKET=ackify-documents
ACKIFY_STORAGE_S3_ACCESS_KEY=your_access_key
ACKIFY_STORAGE_S3_SECRET_KEY=your_secret_key
ACKIFY_STORAGE_S3_REGION=us-east-1
ACKIFY_STORAGE_S3_USE_SSL=true

Using MinIO (Self-hosted S3)

MinIO is a popular open-source S3-compatible storage solution:

ACKIFY_STORAGE_TYPE=s3
ACKIFY_STORAGE_S3_ENDPOINT=http://minio:9000
ACKIFY_STORAGE_S3_BUCKET=ackify-documents
ACKIFY_STORAGE_S3_ACCESS_KEY=minioadmin
ACKIFY_STORAGE_S3_SECRET_KEY=minioadmin
ACKIFY_STORAGE_S3_REGION=us-east-1
ACKIFY_STORAGE_S3_USE_SSL=false

Supported File Types

• PDF documents (.pdf)
• Images (.png, .jpg, .jpeg, .gif, .webp)
• Office documents (.doc, .docx)
• Text files (.txt)
• HTML files (.html, .htm)

Anonymous Telemetry

Ackify can collect anonymous usage metrics to help improve the project.

What is collected

Business metrics only:

• Number of documents created
• Number of signatures/confirmations
• Number of webhooks configured
• Number of email reminders sent

What is NOT collected

• No personal data
• No user information (names, emails, IPs)
• No document content
• No authentication details

Privacy

• GDPR compliant - No personal data is ever collected
• Non-intrusive - Runs in background, no impact on performance
• Opt-in - Disabled by default, you choose to enable it

Configuration

# Enable anonymous telemetry (default: false)
ACKIFY_TELEMETRY=true

We encourage you to enable telemetry to help us improve Ackify for everyone!

SMTP Configuration

SMTP is used for:

• Email reminders for document signatures
• MagicLink authentication

Popular SMTP Providers:

Gmail:

1. Enable 2FA on your Google account
2. Create an App Password at https://myaccount.google.com/apppasswords
3. Use settings:

   MAIL_HOST=smtp.gmail.com
   MAIL_PORT=587
   MAIL_USERNAME=your-email@gmail.com
   MAIL_PASSWORD=your-app-password
   

SMTP2GO: https://www.smtp2go.com/ SendGrid: https://sendgrid.com/ Mailgun: https://www.mailgun.com/

Configuration Variables Reference

See .env.example for a complete list of configuration variables with detailed comments.

Required Variables

APP_BASE_URL=https://your-domain.com
APP_ORGANISATION="Your Organization"
POSTGRES_USER=ackifyr
POSTGRES_PASSWORD=generated_password
POSTGRES_DB=ackify
OAUTH_COOKIE_SECRET=generated_secret
ED25519_PRIVATE_KEY_B64=generated_key
ADMIN_EMAILS=admin@your-domain.com

Note: At least one authentication method (OAuth or MagicLink) must also be configured.

Optional Variables

• OAUTH_ALLOWED_DOMAIN - Restrict sign-ins to specific email domain
• OAUTH_AUTO_LOGIN - Automatically log in if OAuth session exists
• MAIL_* - SMTP configuration for email features
• AUTH_MAGICLINK_ENABLED - Force enable/disable MagicLink
• ONLY_ADMIN_CAN_CREATE - Restrict document creation to admins only (default: false)
• ACKIFY_TELEMETRY - Enable anonymous usage metrics (default: false)
• ACKIFY_STORAGE_TYPE - Document storage type: local or s3 (default: disabled)
• ACKIFY_STORAGE_MAX_SIZE_MB - Maximum upload file size in MB (default: 50)
• ACKIFY_STORAGE_S3_* - S3-compatible storage configuration

Troubleshooting

No authentication method enabled

Error: "At least ONE authentication method must be enabled!"

Solution: Configure either:

• OAuth (set OAUTH_CLIENT_ID and OAUTH_CLIENT_SECRET)
• MagicLink (set MAIL_HOST and SMTP credentials)

OAuth not working

1. Verify redirect URI in OAuth provider settings:

   https://your-domain.com/auth/callback
   

2. Check OAuth credentials are correct in .env

3. Verify APP_BASE_URL matches your domain

MagicLink emails not sending

1. Verify SMTP credentials are correct
2. Check SMTP host and port settings
3. Review logs: docker compose logs -f ackify-ce
4. Test SMTP connection with your provider's tools

Permission denied errors

Make sure Docker has necessary permissions:

sudo usermod -aG docker $USER
newgrp docker

Updating Ackify

To update to the latest version:

cd ackify-ce
docker compose pull
docker compose up -d

Support

• Documentation: https://github.com/btouchard/ackify-ce
• Issues: https://github.com/btouchard/ackify-ce/issues