Installation

Get Atria up and running on your local machine in minutes. This guide covers the quickest path to a working development environment.

Using atria.gg?

This installation guide is for developers and self-hosters who want to run their own Atria instance. If you're using the managed platform at atria.gg, you can skip this page and head straight to the Core Concepts or Event Management guides to learn how to use Atria.

Prerequisites

Before you begin, ensure you have the following installed:

Docker (20.10+) and Docker Compose (v2.0+)
- Install Docker Desktop (includes Docker Compose)
Git for cloning the repository

Recommended but Optional

tmux - Used by the development scripts for managing multiple services
If you don't have tmux, you can run Docker Compose commands directly

Quick Start (5 Minutes)

The fastest way to get Atria running locally:

1. Clone the Repository

git clone https://github.com/thesubtleties/atria.git
cd atria

2. Set Up Environment Variables

Copy the environment files (you need BOTH):

cp .env.example .env                                # For Docker Compose
cp .env.development.example .env.development        # For backend app

Why two files?

.env → Used by Docker Compose to set up PostgreSQL (minimal config)
.env.development → Used by the Flask backend application (full config)

For local development, the defaults work out of the box!

For production or customization, edit .env.development with:

# Database (required)
POSTGRES_USER=dev_user
POSTGRES_PASSWORD=dev_password
POSTGRES_DB=atria_dev

# Security (required)
SECRET_KEY=change-this-secret-key-in-production
JWT_SECRET_KEY=change-this-jwt-secret-in-production

# Encryption key for Mux credentials and sensitive data (required)
# Generate with: python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
ENCRYPTION_KEY=change-this-encryption-key-in-production

# MinIO/S3 credentials (for file uploads)
MINIO_ENDPOINT=localhost:9000
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin

# Email settings (for invitations) - optional
SMTP2GO_API_KEY=your_smtp2go_api_key_here
MAIL_DEFAULT_SENDER=noreply@your-domain.com

# Redis URL (for caching and real-time features) - optional
# REDIS_URL=redis://localhost:6379/0

Required Environment Variables

ENCRYPTION_KEY is required for storing sensitive data like Mux streaming credentials
SECRET_KEY and JWT_SECRET_KEY should be changed for production
Generate secure keys: python -c "import secrets; print(secrets.token_urlsafe(32))"

Optional Services

MinIO/S3: Required for file uploads (event logos, banners, sponsor images). See Storage Configuration.
Email (SMTP2GO): Required for invitation emails. The app gracefully degrades without it.
Redis: Optional but recommended for caching and real-time features. The app works without it.

3. Choose Your Development Environment

Atria provides multiple development environments. For first-time setup, use the interactive chooser:

./dev-environment-chooser.sh

Select option 1) Standard Local Development for the simplest setup.

Alternatively, run the script directly:

./scripts/dev/start-local-dev-tmux.sh

4. Access Atria

Once the containers are running:

Frontend: http://localhost:5173
Backend API: http://localhost:5000
API Documentation: http://localhost:5000/new-swagger

5. Create Your First Account

Navigate to http://localhost:5173
Click "Sign Up" and create an account
Create your first organization
Start exploring!

Development Environments

Atria offers 4 different development environments for different use cases. Use the interactive chooser to switch between them:

./dev-environment-chooser.sh

1. Standard Local Development

Best for: General development, UI work, getting started

./scripts/dev/start-local-dev-tmux.sh

Features:

Single backend instance
No Redis (in-memory Socket.IO)
Direct port access (5000, 5173)
Fastest startup
Hot reload for both frontend and backend

Services:

Backend: localhost:5000
Frontend (Vite dev server): localhost:5173
PostgreSQL: localhost:5432

2. Redis + Traefik Development

Best for: Testing clustering, Socket.IO, caching, production-like behavior

./scripts/dev/start-redis-dev-tmux.sh

Features:

Two backend instances (clustered)
Redis for Socket.IO pub/sub + caching
Traefik load balancer
Production-like environment

Services:

Load Balancer (Traefik): localhost:80
Backend instances: 2 replicas
Redis: localhost:6379
PostgreSQL: localhost:5432

Use this when:

Testing multi-instance deployments
Verifying Socket.IO works across instances
Testing Redis caching behavior
Simulating production load balancing

3. Production Preview (nginx)

Best for: Testing SEO, performance, production builds

./scripts/dev/start-preview-tmux.sh

Features:

Builds frontend with pre-rendering
Serves with nginx (compression, HTTP/2)
Production-accurate performance
No hot reload (requires rebuild)

Services:

Frontend (nginx): localhost:8080
Backend: localhost:5000

Use this when:

Testing production build performance
Verifying SEO and meta tags
Benchmarking page load times
Testing nginx configurations

4. Tailscale Mobile Testing

Best for: Mobile/phone testing, remote access

./scripts/dev/start-tailscale-dev-tmux.sh

Features:

Redis + Traefik (production-like)
Configured for Tailscale remote access
Two backend instances (clustered)

Requires:

Tailscale installed and configured
Access from mobile devices on the same Tailscale network

Configuration

Database Seeding

Some dev environments support database seeding with demo data:

# With Redis/Traefik environment
./scripts/dev/start-redis-dev-tmux.sh
# You'll be prompted: "Seed the database? (y/N)"

Or set the environment variable:

export SEED_DB=true
./scripts/dev/start-redis-dev-tmux.sh

MinIO / S3 Storage

Atria uses MinIO (S3-compatible storage) for file uploads. You have several options:

Option 1: Use External MinIO (Recommended for Development)

Set these environment variables in your .env.development:

# MinIO Configuration
MINIO_ENDPOINT=minio.yourserver.com:9000  # Your MinIO instance
MINIO_ACCESS_KEY=your_access_key
MINIO_SECRET_KEY=your_secret_key
MINIO_USE_SSL=true
MINIO_EXTERNAL_URL=https://storage.yourserver.com  # For presigned URLs

# Optional: Custom bucket names
MINIO_BUCKET_PUBLIC=atria-public
MINIO_BUCKET_AUTHENTICATED=atria-authenticated
MINIO_BUCKET_PRIVATE=atria-private

Option 2: Run MinIO Locally

Run MinIO in Docker:

docker run -d \
  --name atria-minio \
  -p 9000:9000 \
  -p 9001:9001 \
  -e "MINIO_ROOT_USER=minioadmin" \
  -e "MINIO_ROOT_PASSWORD=minioadmin" \
  -v minio_data:/data \
  minio/minio:latest \
  server /data --console-address ":9001"

Or add to your Docker Compose file if preferred (requires manual setup):

# Can be added to docker-compose files if needed
services:
  minio:
    image: minio/minio:latest
    command: server /data --console-address ":9001"
    ports:
      - "9000:9000"
      - "9001:9001"
    environment:
      - MINIO_ROOT_USER=minioadmin
      - MINIO_ROOT_PASSWORD=minioadmin
    volumes:
      - minio_data:/data

Then configure:

MINIO_ENDPOINT=localhost:9000
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin
MINIO_USE_SSL=false
MINIO_EXTERNAL_URL=http://localhost:9000

Option 3: Use AWS S3 or Compatible Service

MinIO is S3-compatible, so you can use any S3-compatible storage:

# AWS S3
MINIO_ENDPOINT=s3.amazonaws.com
MINIO_ACCESS_KEY=<your-aws-access-key>
MINIO_SECRET_KEY=<your-aws-secret-key>
MINIO_USE_SSL=true
MINIO_EXTERNAL_URL=https://s3.amazonaws.com

# Wasabi
MINIO_ENDPOINT=s3.wasabisys.com
# ... etc

# Backblaze B2 (via S3-compatible API)
MINIO_ENDPOINT=s3.us-west-002.backblazeb2.com
# ... etc

tip

The MinIO Python client works with any S3-compatible storage provider. Just change the endpoint and credentials!

Email Configuration (Optional)

Atria uses SMTP2GO for transactional emails. Without configuration, email features will be disabled but the app will work fine.

# SMTP2GO Configuration (optional)
SMTP2GO_API_KEY=your_api_key
MAIL_DEFAULT_SENDER=noreply@yourdomain.com
FRONTEND_URL=http://localhost:5173

Redis Configuration (Optional for Standard Dev)

Redis is optional in development. When not configured, Atria uses in-memory alternatives:

# Redis (optional in development)
REDIS_URL=redis://localhost:6379/0

# Socket.IO can use separate Redis instance
SOCKETIO_REDIS_URL=redis://localhost:6379/1

What happens without Redis:

Socket.IO uses in-memory adapter (single instance only)
Caching disabled (all queries hit database)
No presence tracking/typing indicators
App remains fully functional for development

Troubleshooting

Port Already in Use

If you see "port already in use" errors:

# Check what's using the ports
lsof -i :5000  # Backend
lsof -i :5173  # Frontend
lsof -i :5432  # PostgreSQL

# Stop all running environments
./dev-environment-chooser.sh
# Select option "6) Stop All"

Database Connection Issues

# Reset the database
docker-compose -f docker-compose.local-dev.yml down -v
docker-compose -f docker-compose.local-dev.yml up -d

# Check database logs
docker logs atria-db-dev

Frontend Not Loading

# Rebuild frontend container
docker-compose -f docker-compose.local-dev.yml up -d --build frontend

MinIO Connection Errors

# Verify MinIO endpoint is reachable
curl http://your-minio-endpoint:9000

# Check backend logs for storage errors
docker logs atria-api-dev

Production Deployment

For production deployments, Atria includes a base docker-compose.production.yml file. This requires customization based on your infrastructure needs.

Base Production Setup

The production compose file provides a starting point:

# docker-compose.production.yml (base template)
services:
  backend:
    build:
      context: ./backend/atria
      dockerfile: ../../deploy/Dockerfile.backend.prod
    expose:
      - '5000'
    env_file:
      - ./backend/atria/.flaskenv
      - .env.production
    depends_on:
      db:
        condition: service_healthy
    networks:
      - default
      - shared_portainer_network  # Example: Portainer integration

  frontend:
    build:
      context: ./frontend
      dockerfile: ../deploy/Dockerfile.frontend.prod
    expose:
      - '80'
    depends_on:
      - backend

  db:
    image: postgres:15-alpine
    volumes:
      - postgres_data_prod:/var/lib/postgresql/data
    environment:
      - POSTGRES_USER=${POSTGRES_USER}
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
      - POSTGRES_DB=${POSTGRES_DB}
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready']

Production Requirements

You will need to configure:

Reverse Proxy / Load Balancer
- Nginx, Traefik, Caddy, or similar
- SSL/TLS certificates
- Domain routing
External Services
- Redis - Required for multi-instance deployments and Socket.IO clustering
- PostgreSQL - Can use the Docker container or external database
- S3-compatible storage - MinIO, AWS S3, Backblaze B2, etc.
Environment Configuration
- Create .env.production with production credentials
- Configure all required services (Redis, MinIO, SMTP, etc.)
- Set appropriate security headers and CORS settings
- Content Security Policy (CSP): Configure in frontend/csp-header.conf
  - Pre-configured for Vimeo, Mux, Zoom, and Jitsi streaming
  - Update production-specific domains:
    - storage.sbtl.dev → Your MinIO/S3 endpoint
    - avatars.atria.gg → Your avatar service domain
    - wss://atria.gg → Your WebSocket domain
  - Jitsi domains (*.8x8.vc, *.jitsi.net) are pre-configured
Infrastructure Considerations
- Container orchestration (Docker Swarm, Kubernetes, etc.)
- Backup strategy (database, file storage)
- Monitoring and logging
- Scaling strategy (horizontal scaling requires Redis)

Production Checklist

Production Customization Required

The base docker-compose.production.yml is a template and requires customization for your specific infrastructure. It's designed to give you a starting point, not a ready-to-deploy solution.

Managed Hosting Alternative

If you prefer not to manage infrastructure, consider using atria.gg managed hosting or contact us about a custom private instance with managed setup and maintenance.

Next Steps

API Documentation - Explore the REST API
GitHub Repository - View source code and contribute
GitHub Discussions - Ask questions and share ideas

Having trouble? Open an issue on GitHub or contact us.

Prerequisites​

Quick Start (5 Minutes)​

1. Clone the Repository​

2. Set Up Environment Variables​

3. Choose Your Development Environment​

4. Access Atria​

5. Create Your First Account​

Development Environments​

1. Standard Local Development​

2. Redis + Traefik Development​

3. Production Preview (nginx)​

4. Tailscale Mobile Testing​

Configuration​

Database Seeding​

MinIO / S3 Storage​

Option 1: Use External MinIO (Recommended for Development)​

Option 2: Run MinIO Locally​

Option 3: Use AWS S3 or Compatible Service​

Email Configuration (Optional)​

Redis Configuration (Optional for Standard Dev)​

Troubleshooting​

Port Already in Use​

Database Connection Issues​

Frontend Not Loading​

MinIO Connection Errors​

Production Deployment​

Base Production Setup​

Production Requirements​

Production Checklist​

Next Steps​

Prerequisites

Quick Start (5 Minutes)

1. Clone the Repository

2. Set Up Environment Variables

3. Choose Your Development Environment

4. Access Atria

5. Create Your First Account

Development Environments

1. Standard Local Development

2. Redis + Traefik Development

3. Production Preview (nginx)

4. Tailscale Mobile Testing

Configuration

Database Seeding

MinIO / S3 Storage

Option 1: Use External MinIO (Recommended for Development)

Option 2: Run MinIO Locally

Option 3: Use AWS S3 or Compatible Service

Email Configuration (Optional)

Redis Configuration (Optional for Standard Dev)

Troubleshooting

Port Already in Use

Database Connection Issues

Frontend Not Loading

MinIO Connection Errors

Production Deployment

Base Production Setup

Production Requirements

Production Checklist

Next Steps