Stacks

# Installation guide

This guide offers detailed instructions for installing and deploying Stacks using Docker. To install Stacks for Teams, please join our dev program and wait for our approval, which will allow you to download the latest release.

# Prerequisites

  • Docker and Docker Compose installed on your system
  • At least 2GB of available RAM
  • 5GB of free disk space
  • Internet connection for downloading dependencies

# Quick Start with Docker

# 1. Clone or Download the Release

Once you have been approved into the developer program, please download the latest release from the provided link.

# If cloning the repository
unzip stacks-teams.zip
cd stacks-teams

# Or if using release files, extract them to a directory

# 2. Start the Services

docker-compose up -d

This will start three services:

  • Stacks Server (port 3000) - Main application
  • Email Service - Background email processing
  • PostgreSQL Database - Data storage

# 3. Access the Application

Once all services are running, access Stacks at:

http://localhost:3000

# Environment Configuration

# Server Environment Variables

The main server requires the following environment variables. You can customize these in the .env file:

# Core Application Settings

# Application port (default: 3000)
APP_PORT=3000

# Environment mode
NODE_ENV=production

# Enable database query logging (set to false in production)
DEBUG_DB=false

# Security secrets (CHANGE THESE IN PRODUCTION)
COOKIE_SECRET=your-secure-cookie-secret
JWT_SECRET=your-very-secure-jwt-secret

# File management
DELETE_FILES=false  # Whether to permanently delete files when users delete them
CACHE=true          # Enable caching for better performance

# Database Configuration

POSTGRES_HOST=postgres
POSTGRES_PORT=5432
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
POSTGRES_DB=stacks_hono

# Google OAuth (Optional)

To enable Google Calendar integration and OAuth login:

  1. Go to Google Cloud Console (opens new window)
  2. Create a new project or select an existing one
  3. Enable the Google Calendar API
  4. Create OAuth 2.0 credentials
  5. Add your domain/IP to authorized redirect URIs: http://your-domain:3000/auth/google/callback
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
GOOGLE_REDIRECT_URI=http://your-domain:3000/auth/google/callback

# Email Service Environment Variables

The email service handles background email processing:

# SMTP Configuration

# SMTP server settings
SMTP_HOST=smtp.gmail.com        # Your SMTP server
SMTP_PORT=587                   # SMTP port (587 for TLS, 465 for SSL)
SMTP_SECURE=false               # true for SSL (port 465), false for TLS (port 587)
SMTP_USER=your-email@gmail.com  # SMTP username
SMTP_PASSWORD=your-app-password # SMTP password or app password

# Email sender information
SMTP_FROM_NAME=Stacks Notifications
SMTP_FROM_EMAIL=your-email@gmail.com

# Processing settings
EMAIL_PROCESS_INTERVAL=60000    # Check for emails every 60 seconds
PUBLIC_URL=http://localhost:3000  # Your public URL for email links

# Production Deployment

# 1. Security Considerations

Change Default Secrets:

# Generate secure random strings for these values
COOKIE_SECRET=$(openssl rand -base64 32)
JWT_SECRET=$(openssl rand -base64 64)

Database Security:

  • Change the default PostgreSQL password
  • Consider using a managed database service
  • Enable SSL connections if possible

# Maintenance

# Viewing Logs

# View all service logs
docker-compose logs

# View specific service logs
docker-compose logs stacks
docker-compose logs email
docker-compose logs postgres

# Follow logs in real-time
docker-compose logs -f

# Updating

# Stop services
docker-compose down

# Download the latest release and overwrite the current one

# Rebuild and start
docker-compose up -d --build

# Backup

# Backup database
docker-compose exec postgres pg_dump -U postgres stacks_hono > backup.sql

# Backup uploaded files
docker cp $(docker-compose ps -q stacks):/server/uploads ./uploads-backup

# Restore

# Restore database
docker-compose exec -T postgres psql -U postgres stacks_hono < backup.sql

# Restore uploaded files
docker cp ./uploads-backup $(docker-compose ps -q stacks):/server/uploads

# Troubleshooting

# Common Issues

  1. Port already in use:

    • Change the port mapping in docker-compose.yml: "3001:3000"

  2. Database connection failed:

    • Ensure PostgreSQL service is healthy: docker-compose ps
    • Check database credentials in environment variables

  3. Email not sending:

    • Verify SMTP credentials and settings
    • Check email service logs: docker-compose logs email
    • Ensure firewall allows outbound SMTP connections

  4. Google OAuth not working:

    • Verify redirect URI matches exactly
    • Ensure Google Calendar API is enabled
    • Check client ID and secret are correct

# Health Checks

The application includes health check endpoints:

  • Server health: http://localhost:3000/health
  • Check service status: docker-compose ps

# Support

For additional support:

  1. Check the application logs for error messages
  2. Verify all environment variables are set correctly
  3. Ensure all required ports are available
  4. Check Docker and Docker Compose versions are up to date

Note: This installation guide assumes you're using the Docker deployment method. For development setup or custom installations, refer to the individual package documentation in the packages/ directory.

←