Skip to content

Latest commit

 

History

History
324 lines (256 loc) · 8.32 KB

setup_guide.md

File metadata and controls

324 lines (256 loc) · 8.32 KB

Complete Setup Guide

This guide provides step-by-step instructions for setting up the PSA system using Docker Compose, supporting both Community Edition (CE) and Enterprise Edition (EE).

Prerequisites

  • Docker Engine 24.0.0 or later
  • Docker Compose v2.20.0 or later
  • Git
  • Text editor for configuration files

Initial Setup

  1. Clone the repository:
git clone https://github.com/nine-minds/alga-psa.git
cd alga-psa
  1. Create required directories:
mkdir -p secrets

Secrets Configuration

  1. Create secret files in the secrets/ directory:

Database Secrets:

# Admin user (postgres) - for database administration
echo "your-secure-admin-password" > secrets/postgres_password

# Application user (app_user) - for RLS-controlled access
echo "your-secure-app-password" > secrets/db_password_server

# Hocuspocus service
echo "your-secure-hocuspocus-password" > secrets/db_password_hocuspocus

Redis Secret:

echo "your-secure-password" > secrets/redis_password

Authentication Secret:

# Authentication key for password hashing
echo "your-32-char-min-key" > secrets/alga_auth_key

Security Secrets:

echo "your-32-char-min-key" > secrets/crypto_key
echo "your-32-char-min-key" > secrets/token_secret_key
echo "your-32-char-min-key" > secrets/nextauth_secret

Email & OAuth Secrets:

echo "your-email-password" > secrets/email_password
echo "your-client-id" > secrets/google_oauth_client_id
echo "your-client-secret" > secrets/google_oauth_client_secret
  1. Set proper permissions:
chmod 600 secrets/*

Environment Configuration

  1. Copy the appropriate environment template:
cp .env.example server/.env
  1. Edit the environment file and configure required values:

Required Variables:

# Database Configuration
DB_TYPE=postgres  # Must be "postgres"
DB_USER_ADMIN=postgres  # Admin user for database operations

# Logging Configuration
LOG_LEVEL=INFO  # One of: SYSTEM, TRACE, DEBUG, INFO, WARNING, ERROR, CRITICAL
LOG_IS_FORMAT_JSON=false
LOG_IS_FULL_DETAILS=false

# Email Configuration
EMAIL_ENABLE=false  # Set to "true" to enable email notifications
[email protected]  # Must be valid email
EMAIL_HOST=smtp.gmail.com  # SMTP server hostname
EMAIL_PORT=587  # SMTP port (587 for TLS, 465 for SSL)
[email protected]  # SMTP username

# Authentication Configuration
NEXTAUTH_URL=http://localhost:3000  # Must be valid URL
NEXTAUTH_SESSION_EXPIRES=86400  # Must be > 0

Optional Variables:

# Hocuspocus Configuration
REQUIRE_HOCUSPOCUS=false  # Set to "true" to require hocuspocus service

Note: The system performs validation of these environment variables at startup. Missing or invalid values will prevent the system from starting.

Database Configuration

The system uses a two-user database authentication model for security:

  1. Admin User:

    • Username: postgres
    • Password: Stored in postgres_password secret
    • Purpose: Database administration, setup, migrations
    • Access: Full database access
    • Used by: Setup scripts, migrations, administrative tasks

  2. Application User:

    • Username: app_user
    • Password: Stored in db_password_server secret
    • Purpose: Application database access
    • Access: Limited by Row Level Security (RLS) policies
    • Used by: Application services, regular operations

This separation ensures:

  • Principle of least privilege
  • Data access control through RLS
  • Clear separation of administrative and application operations

Docker Compose Configuration

Community Edition (CE)

  1. For development:
docker compose -f docker-compose.base.yaml -f docker-compose.ce.yaml up
  1. For production:
docker compose -f docker-compose.base.yaml -f docker-compose.ce.yaml -f docker-compose.prod.yaml up -d

Enterprise Edition (EE)

  1. For development:
docker compose -f docker-compose.base.yaml -f docker-compose.ee.yaml up
  1. For production:
docker compose -f docker-compose.base.yaml -f docker-compose.ee.yaml -f docker-compose.prod.yaml up -d

Service Initialization

The entrypoint scripts will automatically:

  1. Validate environment variables
  2. Check dependencies
  3. Initialize database with both users
  4. Set up RLS policies
  5. Run database migrations
  6. Seed initial data (in development)
  7. Start services

You can monitor the initialization process through Docker logs:

docker compose logs -f

Initial Login Credentials

After successful initialization, the server logs will display a sample username and password that can be used for initial access:

docker compose logs -f

Verification

  1. Check service health:
docker compose ps
  1. Access the application:
  1. Verify logs for any errors:
docker compose logs [service-name]

Common Issues & Solutions

Environment Validation Issues

  • Check all required variables are set
  • Verify DB_TYPE is set to "postgres"
  • Ensure LOG_LEVEL is a valid value
  • Verify email addresses are valid
  • Check numeric values are > 0
  • Verify URLs are valid

Database Connection Issues

  • Verify secret files exist and have correct permissions
  • Check database host/port configuration
  • Ensure PostgreSQL container is running
  • Verify postgres_password for admin operations
  • Verify db_password_server for application access
  • Check RLS policies if access is denied

Redis Connection Issues

  • Verify redis_password secret exists
  • Check redis host/port configuration
  • Ensure Redis container is running

Authentication Issues

  • Verify alga_auth_key secret exists and is properly configured
  • Ensure authentication key is at least 32 characters long
  • Check permissions on alga_auth_key secret file

Hocuspocus Issues

  • Check REQUIRE_HOCUSPOCUS setting
  • Verify service availability if required
  • Check connection timeout settings
  • Verify database access

Service Startup Issues

  • Check service logs for specific errors
  • Verify all required secrets exist
  • Ensure correct environment variables are set
  • Verify database users and permissions

Security Checklist

✓ All secrets created with secure values ✓ Secret files have restricted permissions (600) ✓ Environment files configured without sensitive data ✓ Production environment uses HTTPS ✓ Database passwords are strong and unique ✓ Redis password is configured ✓ Authentication key (alga_auth_key) is properly configured ✓ Encryption keys are at least 32 characters ✓ RLS policies properly configured ✓ Database users have appropriate permissions ✓ Environment variables properly validated

Next Steps

  1. Configure email notifications:
    • Set environment variables: 
      EMAIL_ENABLE=true
EMAIL_HOST=smtp.example.com
EMAIL_PORT=587  # or 465 for SSL
[email protected]
EMAIL_PASSWORD=your-secure-password
[email protected]
    • Run migrations to set up notification tables: 
      cd server && npx knex migrate:latest
    • Seed default templates and categories: 
      cd server && npx knex seed:run
    • Features available after setup:
      • System-wide default templates
      • Tenant-specific template customization
      • User notification preferences
      • Rate limiting and audit logging
      • Categories: Tickets, Invoices, Projects, Time Entries
  2. Set up OAuth if using Google authentication
  3. Configure SSL/TLS for production
  4. Set up backup procedures
  5. Configure monitoring and logging
  6. Review security settings
  7. Review and test RLS policies

Upgrading

When upgrading from a previous version:

  1. Backup all data:
docker compose exec postgres pg_dump -U postgres server > backup.sql
  1. Update the repository:
git pull origin main
  1. Review changes in:
  • Docker Compose files
  • Environment variables
  • Secret requirements
  • Database schema
  • RLS policies
  • Protocol Buffer definitions (EE only)

  1. Update configurations as needed

  2. Rebuild and restart:

docker compose down
docker compose up -d --build

Additional Resources