Skip to content

Latest commit

 

History

History
208 lines (151 loc) · 4.34 KB

getting-started.md

File metadata and controls

208 lines (151 loc) · 4.34 KB

Getting Started

Installation and configuration guide for Ackify with Docker Compose.

Prerequisites

  • Docker and Docker Compose installed
  • A domain (or localhost for testing)
  • OAuth2 credentials (Google, GitHub, GitLab, or custom)

Quick Installation

1. Clone the repository

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

2. Configuration

Copy the example file and edit it:

cp .env.example .env
nano .env

Minimum required variables:

# Public domain of your instance
APP_DNS=sign.your-domain.com
ACKIFY_BASE_URL=https://sign.your-domain.com
ACKIFY_ORGANISATION="Your Organization Name"

# PostgreSQL database
POSTGRES_USER=ackifyr
POSTGRES_PASSWORD=your_secure_password_here
POSTGRES_DB=ackify

# OAuth2 (example with Google)
ACKIFY_OAUTH_PROVIDER=google
ACKIFY_OAUTH_CLIENT_ID=your_google_client_id
ACKIFY_OAUTH_CLIENT_SECRET=your_google_client_secret

# Security - generate with: openssl rand -base64 32
ACKIFY_OAUTH_COOKIE_SECRET=your_base64_encoded_secret_key

3. Start

docker compose up -d

This command will:

  • Download necessary Docker images
  • Start PostgreSQL with healthcheck
  • Apply database migrations
  • Launch the Ackify application

4. Verification

# View logs
docker compose logs -f ackify-ce

# Check health endpoint
curl http://localhost:8080/api/v1/health
# Expected: {"status":"healthy","database":"connected"}

5. Access the interface

Open your browser:

OAuth2 Configuration

Before using Ackify, configure your OAuth2 provider.

Google OAuth2

  1. Go to Google Cloud Console
  2. Create a new project or select an existing one
  3. Enable the "Google+ API"
  4. Create OAuth 2.0 credentials:
    • Type: Web application
    • Authorized redirect URIs: https://sign.your-domain.com/api/v1/auth/callback
  5. Copy the Client ID and Client Secret to .env
ACKIFY_OAUTH_PROVIDER=google
ACKIFY_OAUTH_CLIENT_ID=123456789-abc.apps.googleusercontent.com
ACKIFY_OAUTH_CLIENT_SECRET=GOCSPX-xyz...

GitHub OAuth2

  1. Go to GitHub Developer Settings
  2. Create a new OAuth App
  3. Configuration:
    • Homepage URL: https://sign.your-domain.com
    • Callback URL: https://sign.your-domain.com/api/v1/auth/callback
  4. Generate a client secret
ACKIFY_OAUTH_PROVIDER=github
ACKIFY_OAUTH_CLIENT_ID=Iv1.abc123
ACKIFY_OAUTH_CLIENT_SECRET=ghp_xyz...

See OAuth Providers for GitLab and custom providers.

Generating Secrets

# Cookie secret (required)
openssl rand -base64 32

# Ed25519 private key (optional, auto-generated if missing)
openssl rand -base64 64

First Steps

Create your first signature

  1. Go to http://localhost:8080/?doc=test_document
  2. Click "Sign this document"
  3. Login via OAuth2
  4. Validate the signature

Access the admin dashboard

  1. Add your email in .env: 
    ACKIFY_ADMIN_EMAILS=admin@company.com
  2. Restart: 
    docker compose restart ackify-ce
  3. Login and access /admin

Embed in a page

<!-- Embeddable widget -->
<iframe src="https://sign.your-domain.com/?doc=test_document"
        width="600" height="200"
        frameborder="0"
        style="border: 1px solid #ddd; border-radius: 6px;"></iframe>

Useful Commands

# View logs
docker compose logs -f ackify-ce

# Restart
docker compose restart ackify-ce

# Stop
docker compose down

# Rebuild after changes
docker compose up -d --force-recreate ackify-ce --build

# Access the database
docker compose exec ackify-db psql -U ackifyr -d ackify

Troubleshooting

Application doesn't start

# Check logs
docker compose logs ackify-ce

# Check PostgreSQL health
docker compose ps ackify-db

Migration error

# Manually re-run migrations
docker compose up ackify-migrate

OAuth callback error

Verify that:

  • ACKIFY_BASE_URL exactly matches your domain
  • The callback URL in the OAuth2 provider is correct
  • The cookie secret is properly configured

Next Steps