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

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

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)

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