Skip to main content

​
Overview

Autumn is fully open-source and can be self-hosted on your own infrastructure. This guide will walk you through setting up Autumn using Docker Compose.

​
Prerequisites

Before you begin, make sure you have the following installed:

​
Architecture

The self-hosted Autumn setup includes:
  • Vite Frontend - React dashboard on port 3000
  • Server - Hono API server on port 8080
  • Workers - BullMQ background job processors
  • Valkey - Redis-compatible cache on port 6379
  • LocalTunnel - Webhook endpoint for Stripe (development only)

​
Installation

1

Clone the repository

git clone https://github.com/useautumn/autumn.git
cd autumn
2

Install dependencies

bun install
3

Run the setup script

The setup script will guide you through configuration:
bun setup
This will:
  • Generate encryption keys for secure data storage
  • Set up Stripe webhook endpoints
  • Optionally create a Supabase database instance
  • Create the server/.env file with all required variables
4

Generate database schema

Create the database tables:
bun db:generate && bun db:migrate

​
Environment Configuration

The setup script creates a server/.env file. Here are the key environment variables:

​
Required Variables

# Auth configuration
BETTER_AUTH_SECRET=your-secret-key
BETTER_AUTH_URL=http://localhost:8080
CLIENT_URL=http://localhost:3000

​
Optional Variables

# Google OAuth (optional)
# Get from https://console.cloud.google.com/apis/credentials
GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret
If you’re using your own Postgres instance instead of Supabase, simply paste your connection string in DATABASE_URL and leave the Supabase variables empty.

​
Running with Docker Compose

Autumn includes Docker Compose configurations for different platforms:
1

Start the services

docker compose -f docker-compose.dev.yml up
Add the -d flag to run in detached mode:
docker compose -f docker-compose.unix.yml up -d
2

Verify services are running

Check that all services are healthy:
docker compose ps
You should see:
  • vite - Frontend (port 3000)
  • server - API server (port 8080)
  • workers - Background jobs
  • valkey - Redis cache (port 6379)
  • shared - Shared packages
  • localtunnel - Webhook tunnel
3

Access the dashboard

Open your browser and navigate to:
http://localhost:3000

​
Docker Services Explained

​
Valkey (Redis)

Provides caching and job queue storage: 
valkey:
  image: docker.io/valkey/valkey:8.0
  ports:
    - "6379:6379"
  volumes:
    - valkey-data:/valkey/valkey/data

​
Vite Frontend

React-based dashboard application: 
vite:
  build:
    dockerfile: docker/dev.dockerfile
    target: vite
  ports:
    - "3000:3000"
  environment:
    - NODE_ENV=development

​
Server

Hono-based API server: 
server:
  build:
    dockerfile: docker/dev.dockerfile
    target: server
  ports:
    - "8080:8080"
  environment:
    - NODE_ENV=development
    - REDIS_URL=redis://valkey:6379

​
Workers

BullMQ background job processors: 
workers:
  build:
    dockerfile: docker/dev.dockerfile
    target: workers
  environment:
    - REDIS_URL=redis://valkey:6379

​
Authentication Setup

​
Development Mode

In development, Autumn uses console-based OTP authentication:
  1. Navigate to http://localhost:3000
  2. Enter your email address
  3. Check your terminal/console for the OTP code
  4. Enter the OTP to sign in
The OTP will appear in the logs of the server container. If running in detached mode, use docker compose logs server -f to view logs.

​
Production Mode

For production deployments, configure one or both of: Email OTP with Resend: 
RESEND_API_KEY=re_your_api_key
RESEND_DOMAIN=yourdomain.com
Google OAuth: 
GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret

​
Database Configuration

The setup script can automatically provision a Supabase database:
  1. Run bun setup
  2. Choose to create a Supabase instance
  3. The script will configure DATABASE_URL, SUPABASE_URL, and SUPABASE_SERVICE_KEY

​
Using Your Own PostgreSQL

To use your own Postgres instance:
  1. Create a database for Autumn
  2. Update server/.env: 
    DATABASE_URL=postgresql://user:password@host:port/autumn
  3. Run migrations: 
    bun db:generate && bun db:migrate

​
Stripe Configuration

Autumn requires a Stripe account for payment processing:
1

Create a Stripe account

Sign up at stripe.com if you haven’t already.
2

Get your API keys

Navigate to Developers → API keys in your Stripe dashboard and copy your secret key.
3

Configure in Autumn

Add your Stripe keys in the Autumn dashboard under Settings → Integrations → Stripe.
4

Set up webhooks

The setup script automatically configures webhook endpoints using LocalTunnel for development.For production, configure your webhook endpoint:
https://yourdomain.com/api/webhooks/stripe
Subscribe to these events:
  • customer.subscription.created
  • customer.subscription.updated
  • customer.subscription.deleted
  • invoice.payment_succeeded
  • invoice.payment_failed
  • checkout.session.completed

​
Stopping Services

To stop all running containers: 
docker compose down
To stop and remove volumes (clears data): 
docker compose down -v

​
Production Deployment

For production deployments:
Do not use LocalTunnel in production. Configure a proper domain with SSL/TLS certificates.
  1. Set production environment variables
    • Update BETTER_AUTH_URL and CLIENT_URL to your production domain
    • Configure real email service (Resend) or OAuth
    • Use a production Postgres instance
    • Set up Redis with persistence
  2. Use a production Docker Compose file 
    services:
  vite:
    build:
      target: production
    environment:
      - NODE_ENV=production
  3. Configure reverse proxy Use nginx or Caddy to handle SSL and route traffic:
    • Frontend → port 3000
    • API → port 8080
  4. Set up monitoring Configure Axiom or your preferred logging solution: 
    AXIOM_TOKEN=your-production-token

​
Troubleshooting

​
Database Migration Errors

If you encounter SyntaxError: Unexpected end of JSON input:
  1. Connect to your database
  2. Drop all tables
  3. Run migrations again: 
    bun db:generate && bun db:migrate

​
Service Not Starting

Check container logs: 
# View logs for a specific service
docker compose logs server -f

# View logs for all services
docker compose logs -f

​
Port Conflicts

If ports 3000, 8080, or 6379 are already in use, update the port mappings in your docker-compose.yml file: 
ports:
  - "3001:3000"  # Map to a different host port

​
Redis Connection Issues

Verify Valkey is running: 
docker compose ps valkey
Test Redis connection: 
docker compose exec valkey redis-cli ping
# Should return: PONG

​
Updating Autumn

To update to the latest version: 
git pull origin main
bun install
bun db:generate && bun db:migrate
docker compose down
docker compose build
docker compose up

​
Getting Help

Discord Community

Join our community for real-time support

GitHub Issues

Report bugs or request features

Email Support

Reach out to the team directly

Contributing Guide

Learn how to contribute to Autumn

Build docs developers (and LLMs) love

Get started for freeTalk to us