Self-host astradraw

astradraw README

How to install astradraw

APP_DOMAIN, APP_PROTOCOL, POSTGRES_*, OIDC_*, GIPHY_API_KEY, KINESCOPE_API_KEY, KINESCOPE_PROJECT_ID, JWT_SECRET, STORAGE_BACKEND, S3_*

# 1. Clone this repository
git clone https://github.com/AstraDraw/astradraw.git
cd astradraw/deploy

# 2. Copy environment template
cp env.example .env

# 3. Create secrets
mkdir -p secrets
openssl rand -base64 32 > secrets/jwt_secret
openssl rand -base64 32 > secrets/postgres_password
echo "minioadmin" > secrets/minio_access_key
openssl rand -base64 32 > secrets/minio_secret_key

# 4. Generate self-signed certs for local testing
mkdir -p certs
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout certs/server.key -out certs/server.crt \
  -subj "/CN=draw.local"

# 5. Start all services
docker compose up -d

# 6. Access at https://draw.local (add to /etc/hosts if needed)

How to configure astradraw

• ACME_EMAILEmail for Let's Encrypt certificates (uncomment when using HTTPS)

  Email for Let's Encrypt certificates (uncomment when using HTTPS)

• ADMIN_EMAIL=admin@localhostAdmin email (default: admin@localhost)

  Admin email (default: admin@localhost)

• ADMIN_PASSWORDAdmin password - use secret file for production: echo "secure_password" > secrets/admin_password Or set directly (CHANGE THIS IN PRODUCTION!):

  Admin password - use secret file for production: echo "secure_password" > secrets/admin_password Or set directly (CHANGE THIS IN PRODUCTION!):

• ADMIN_USERNAME=adminAdmin username (default: admin)

  Admin username (default: admin)

• APP_DOMAIN=draw.localYour domain for Excalidraw (e.g., draw.example.com or IP address) For local development, use draw.local (add to /etc/hosts: 127.0.0.1 draw.local)

  Your domain for Excalidraw (e.g., draw.example.com or IP address) For local development, use draw.local (add to /etc/hosts: 127.0.0.1 draw.local)

• APP_PROTOCOL=httpsProtocol to use (http or https) Use 'https' for draw.local with self-signed certs

  Protocol to use (http or https) Use 'https' for draw.local with self-signed certs

• APP_URLFull application URL (constructed from APP_PROTOCOL and APP_DOMAIN) REQUIRED for SSO redirects after login If not set, defaults to http://localhost which will break SSO!

  Full application URL (constructed from APP_PROTOCOL and APP_DOMAIN) REQUIRED for SSO redirects after login If not set, defaults to http://localhost which will break SSO!

• DATABASE_URLOption 3: Use DATABASE_URL directly (supports _FILE suffix)

  Option 3: Use DATABASE_URL directly (supports _FILE suffix)

• DEBUG_NAVIGATION=falseDEBUG CONFIGURATION (Navigation Logging) Enable navigation debugging to troubleshoot scene switching issues. When enabled, navigation events are logged to deploy/logs/navigation.log WARNING: Debug logging may impact performance. Disable in production.

  DEBUG CONFIGURATION (Navigation Logging) Enable navigation debugging to troubleshoot scene switching issues. When enabled, navigation events are logged to deploy/logs/navigation.log WARNING: Debug logging may impact performance. Disable in production.

• ENABLE_LOCAL_AUTH=trueEnable/disable local authentication (default: true when OIDC not configured)

  Enable/disable local authentication (default: true when OIDC not configured)

• ENABLE_REGISTRATION=falseEnable/disable user registration (default: false)

  Enable/disable user registration (default: false)

• GIPHY_API_KEYGIPHY CONFIGURATION (for Stickers & GIFs sidebar) GIPHY API Key for GIF/sticker search functionality Get your free API key at: https://developers.giphy.com/ Use Docker secret: echo "your_api_key" > secrets/giphy_api_key Or set directly:

  GIPHY CONFIGURATION (for Stickers & GIFs sidebar) GIPHY API Key for GIF/sticker search functionality Get your free API key at: https://developers.giphy.com/ Use Docker secret: echo "your_api_key" > secrets/giphy_api_key Or set directly:

• JWT_SECRETAUTHENTICATION - JWT SECRET Secret key for signing JWT tokens. MUST be changed in production! Generate a secure secret: openssl rand -base64 32 Option 1: Use Docker secret (recommended): openssl rand -base64 32 > secrets/jwt_secret Option 2: Set directly (less secure):

  AUTHENTICATION - JWT SECRET Secret key for signing JWT tokens. MUST be changed in production! Generate a secure secret: openssl rand -base64 32 Option 1: Use Docker secret (recommended): openssl rand -base64 32 > secrets/jwt_secret Option 2: Set directly (less secure):

• KINESCOPE_API_KEYKINESCOPE CONFIGURATION (for Talktrack board recordings) Kinescope API Key for video upload and playback Get your API key at: https://app.kinescope.io/ SECURITY: These credentials are used ONLY by the backend service. The frontend proxies all requests through the backend. Use Docker secrets (recommended): echo "your_api_key" > secrets/kinescope_api_key echo "your_project_id" > secrets/kinescope_pr

  KINESCOPE CONFIGURATION (for Talktrack board recordings) Kinescope API Key for video upload and playback Get your API key at: https://app.kinescope.io/ SECURITY: These credentials are used ONLY by the backend service. The frontend proxies all requests through the backend. Use Docker secrets (recommended): echo "your_api_key" > secrets/kinescope_api_key echo "your_project_id" > secrets/kinescope_pr

• KINESCOPE_PROJECT_ID
• OIDC_CLIENT_IDOIDC Client ID (from your identity provider)

  OIDC Client ID (from your identity provider)

• OIDC_CLIENT_SECRETOIDC Client Secret - use secret file for production: echo "your_client_secret" > secrets/oidc_client_secret Or set directly (less secure):

  OIDC Client Secret - use secret file for production: echo "your_client_secret" > secrets/oidc_client_secret Or set directly (less secure):

• OIDC_INTERNAL_URLInternal URL for OIDC discovery (for Docker networking) Use this when your OIDC provider is in the same Docker network Example: http://dex:5556/dex

  Internal URL for OIDC discovery (for Docker networking) Use this when your OIDC provider is in the same Docker network Example: http://dex:5556/dex

• OIDC_ISSUER_URLOIDC Issuer URL (your identity provider URL) Example: https://auth.yourdomain.com/application/o/astradraw/

  OIDC Issuer URL (your identity provider URL) Example: https://auth.yourdomain.com/application/o/astradraw/

• PGADMIN_EMAILpgAdmin (database admin UI) - only used with --profile admin

  pgAdmin (database admin UI) - only used with --profile admin

• PGADMIN_PASSWORD
• POSTGRES_DB=excalidraw
• POSTGRES_HOSTFor external PostgreSQL (outside Docker), set host and port:

  For external PostgreSQL (outside Docker), set host and port:

• POSTGRES_PASSWORD
• POSTGRES_PORT
• POSTGRES_USERDATABASE CONFIGURATION (PostgreSQL) PostgreSQL is used for user management, workspaces, scenes metadata, etc. Option 1: Use Docker secrets (RECOMMENDED for production) Create secret files and the backend will read them automatically: echo "excalidraw" > secrets/postgres_user openssl rand -base64 32 > secrets/postgres_password echo "excalidraw" > secrets/postgres_db Option 2: Set values directly in

  DATABASE CONFIGURATION (PostgreSQL) PostgreSQL is used for user management, workspaces, scenes metadata, etc. Option 1: Use Docker secrets (RECOMMENDED for production) Create secret files and the backend will read them automatically: echo "excalidraw" > secrets/postgres_user openssl rand -base64 32 > secrets/postgres_password echo "excalidraw" > secrets/postgres_db Option 2: Set values directly in

• ROOM_KEY_SECRETROOM KEY SECRET (Auto-Collaboration) Optional: Secret used to encrypt room keys stored in the database. If not set, JWT_SECRET is used automatically. IMPORTANT: This secret can be ANY length - it's hashed with SHA-256 before use. Generate with: openssl rand -base64 32 Note: This is NOT the room key itself. Room keys are 22-character strings (16 bytes base64url encoded) required by AES-128-GCM encr

  ROOM KEY SECRET (Auto-Collaboration) Optional: Secret used to encrypt room keys stored in the database. If not set, JWT_SECRET is used automatically. IMPORTANT: This secret can be ANY length - it's hashed with SHA-256 before use. Generate with: openssl rand -base64 32 Note: This is NOT the room key itself. Room keys are 22-character strings (16 bytes base64url encoded) required by AES-128-GCM encr

• S3_ACCESS_KEYMinIO credentials - use secrets (recommended): echo "minioadmin" > secrets/minio_access_key openssl rand -base64 32 > secrets/minio_secret_key Or set directly (less secure):

  MinIO credentials - use secrets (recommended): echo "minioadmin" > secrets/minio_access_key openssl rand -base64 32 > secrets/minio_secret_key Or set directly (less secure):

• S3_BUCKET=excalidrawS3 bucket name for storing scenes, rooms, and files

  S3 bucket name for storing scenes, rooms, and files

• S3_ENDPOINT=http://minio:9000S3 endpoint URL (default: http://minio:9000 for local MinIO) For AWS S3: https://s3.amazonaws.com For external MinIO: http://your-minio-host:9000

  S3 endpoint URL (default: http://minio:9000 for local MinIO) For AWS S3: https://s3.amazonaws.com For external MinIO: http://your-minio-host:9000

• S3_FORCE_PATH_STYLE=trueForce path-style URLs (required for MinIO, set to false for AWS S3)

  Force path-style URLs (required for MinIO, set to false for AWS S3)

• S3_PUBLIC_URLPublic URL for S3 thumbnails (optional, for production with CDN) If not set, thumbnails use /s3/ path proxied via Traefik

  Public URL for S3 thumbnails (optional, for production with CDN) If not set, thumbnails use /s3/ path proxied via Traefik

• S3_REGION=us-east-1S3 region (can be any value for MinIO)

  S3 region (can be any value for MinIO)

• S3_SECRET_KEY
• STORAGE_BACKENDStorage backend type: 's3' (MinIO/S3) or 'keyv' (PostgreSQL/MongoDB) Recommended: s3 for blob storage (scenes, rooms, files)

  Storage backend type: 's3' (MinIO/S3) or 'keyv' (PostgreSQL/MongoDB) Recommended: s3 for blob storage (scenes, rooms, files)

• STORAGE_BODY_LIMITMaximum payload size for scenes/images

  Maximum payload size for scenes/images

• STORAGE_LOG_LEVELStorage backend log level (debug, verbose, log, warn, error)

  Storage backend log level (debug, verbose, log, warn, error)

• SUPERADMIN_EMAILSSUPER ADMIN CONFIGURATION Super admins have instance-level management capabilities: - Can create and delete workspaces - Can assign workspace admins - Can configure instance settings Comma-separated list of email addresses that should be super admins. Users with these emails will be automatically promoted on login. Use Docker secret for production: echo "admin@example.com,boss@example.com" > secre

  SUPER ADMIN CONFIGURATION Super admins have instance-level management capabilities: - Can create and delete workspaces - Can assign workspace admins - Can configure instance settings Comma-separated list of email addresses that should be super admins. Users with these emails will be automatically promoted on login. Use Docker secret for production: echo "admin@example.com,boss@example.com" > secre