Enfyra
Docs

Enfyra Docker - Usage Guide

Enfyra Docker - Usage Guide New to Enfyra? See the Installation Guide for complete setup instructions, including Docker and manual installation options. Overview The enfyra/enfyra image can run in 3 different modes : all (default) - Run both server + app + embedded services serve

Enfyra Docker - Usage Guide

New to Enfyra? See the Installation Guide for complete setup instructions, including Docker and manual installation options.

Overview

The enfyra/enfyra image can run in 3 different modes:

  1. all (default) - Run both server + app + embedded services
  2. server - Run backend server only
  3. app - Run frontend app only

All from the same image, just different environment variables!

1. Run All-in-One (Server + App + Embedded Services)

Simplest way (single command):

docker run -d \
  --name enfyra \
  -p 3000:3000 \
  -v enfyra-data:/app/data \
  enfyra/enfyra:latest

Runs with: - Server (port 1105 internal) - App (port 3000, exposed) - Embedded PostgreSQL (if no DB config) - Embedded Redis (if no REDIS_URI)

With MySQL (Embedded):

docker run -d \
  --name enfyra \
  -p 3000:3000 \
  -e EMBEDDED_DB=mysql \
  -v enfyra-data:/app/data \
  enfyra/enfyra:latest

With external database and Redis:

docker run -d \
  --name enfyra \
  -p 3000:3000 \
  -e DB_URI=postgresql://enfyra:secret@my-postgres-host:5432/enfyra \
  -e REDIS_URI=redis://my-redis:6379/0 \
  enfyra/enfyra:latest

If the database and Redis are running on your local machine for testing, use host.docker.internal instead of localhost. Inside a container, localhost points to the container itself:

docker run -d \
  --name enfyra \
  -p 3000:3000 \
  -e DB_URI=postgresql://enfyra:[email protected]:5432/enfyra \
  -e REDIS_URI=redis://host.docker.internal:6379/0 \
  enfyra/enfyra:latest

On Linux, add the host gateway mapping if needed:

docker run -d \
  --name enfyra \
  --add-host=host.docker.internal:host-gateway \
  -p 3000:3000 \
  -e DB_URI=postgresql://enfyra:[email protected]:5432/enfyra \
  -e REDIS_URI=redis://host.docker.internal:6379/0 \
  enfyra/enfyra:latest

Your local database and Redis must accept connections from Docker, not only from 127.0.0.1.

Note: The database engine is auto-detected from the DB_URI protocol prefix (mysql://, postgres://, mongodb://). No separate DB_TYPE env var is needed.

2. Run Server Only (Backend)

Run server only, no app:

docker run -d \
  --name enfyra-server \
  -p 1105:1105 \
  -e ENFYRA_MODE=server \
  -e DB_URI=postgresql://enfyra:secret@my-postgres:5432/enfyra \
  -e REDIS_URI=redis://my-redis:6379/0 \
  enfyra/enfyra:latest

With replica databases:

docker run -d \
  --name enfyra-server \
  -p 1105:1105 \
  -e ENFYRA_MODE=server \
  -e DB_URI=postgresql://enfyra:secret@master-postgres:5432/enfyra \
  -e DB_REPLICA_URIS=postgresql://enfyra:secret@replica1:5432/enfyra,postgresql://enfyra:secret@replica2:5432/enfyra \
  -e DB_READ_FROM_MASTER=false \
  -e REDIS_URI=redis://my-redis:6379/0 \
  enfyra/enfyra:latest

Server with embedded services:

docker run -d \
  --name enfyra-server \
  -p 1105:1105 \
  -e ENFYRA_MODE=server \
  -v enfyra-server-data:/app/data \
  enfyra/enfyra:latest

Note: When ENFYRA_MODE=server, app will not be started, only backend API.

3. Run App Only (Frontend)

Run app only, requires API_URL pointing to external server:

docker run -d \
  --name enfyra-app \
  -p 3000:3000 \
  -e ENFYRA_MODE=app \
  -e API_URL=http://your-server-host:1105/ \
  enfyra/enfyra:latest

App with HTTPS backend:

docker run -d \
  --name enfyra-app \
  -p 3000:3000 \
  -e ENFYRA_MODE=app \
  -e API_URL=https://api.your-domain.com/ \
  enfyra/enfyra:latest

Note: - When ENFYRA_MODE=app, must set API_URL - Server and embedded services will not be started

Mode Comparison

Mode Server App Embedded Redis Embedded DB Use Case
all (default) (if no REDIS_URI) (if no DB config) Single container, simple
server (if no REDIS_URI) (if no DB config) Backend API only, cluster
app Frontend only, scale separately

Scaling with Multiple Containers

Scale Server (Backend cluster):

# Server node 1
docker run -d \
  --name enfyra-server-1 \
  -p 1105:1105 \
  -e ENFYRA_MODE=server \
  -e DB_URI=postgresql://enfyra:secret@shared-postgres:5432/enfyra \
  -e REDIS_URI=redis://shared-redis:6379/0 \
  enfyra/enfyra:latest

# Server node 2
docker run -d \
  --name enfyra-server-2 \
  -p 1106:1105 \
  -e ENFYRA_MODE=server \
  -e DB_URI=postgresql://enfyra:secret@shared-postgres:5432/enfyra \
  -e REDIS_URI=redis://shared-redis:6379/0 \
  enfyra/enfyra:latest

# App (pointing to load balancer or server nodes)
docker run -d \
  --name enfyra-app \
  -p 3000:3000 \
  -e ENFYRA_MODE=app \
  -e API_URL=http://load-balancer:1105/ \
  enfyra/enfyra:latest

Environment Variables Reference

Mode

  • ENFYRA_MODE: all, server, or app (default: all)

Database (if not set uses embedded)

  • EMBEDDED_DB: Embedded database type when no DB_URI is set: postgres or mysql (default: postgres). Has no effect when DB_URI is provided.

Primary (Recommended): - DB_URI: Database connection URI — the database type is auto-detected from the URI protocol, so DB_TYPE does not need to be set. - PostgreSQL: postgresql://user:password@host:port/database - MySQL: mysql://user:password@host:port/database - MongoDB: mongodb://user:password@host:port/database?authSource=admin - Example: postgresql://enfyra:secret@my-postgres:5432/enfyra - Note: URL-encode special characters in password if needed (@ %40, : %3A, / %2F, % %25, # %23, ? %3F, & %26)

Replica Configuration (Optional): - DB_REPLICA_URIS: Comma-separated replica URIs - Example: postgresql://user:pass@replica1:5432/db,postgresql://user:pass@replica2:5432/db - DB_READ_FROM_MASTER: Include master in read pool (true/false, default: false) - false: Read queries only use replicas (master only for writes) - true: Read queries use master + replicas (round-robin)

Redis (if not set uses embedded)

  • REDIS_URI: Redis connection string
  • Format: redis://user:pass@host:port/db or redis://host:port/db
  • DEFAULT_TTL: Default TTL for cache entries in seconds (default: 5)
  • REDIS_RUNTIME_CACHE: Store Enfyra runtime definition snapshots in Redis instead of per-instance memory (false by default)
  • REDIS_USER_CACHE_LIMIT_MB: Soft allocation for $cache / @CACHE user data (30 by default)
  • REDIS_USER_CACHE_MAX_VALUE_BYTES: Optional per-value limit for $cache / @CACHE; 0 disables the cap

Server

  • PORT: Server port (default: 1105)
  • ENFYRA_SERVER_WORKERS: Number of workers for cluster (default: 1)
  • SECRET_KEY: Server secret used for auth token signing and isEncrypted=true field encryption (default: enfyra_secret_key_change_in_production)
  • NODE_NAME: Node instance name for logs/cluster (default: auto-generated UUID - ensures 100% uniqueness across nodes)

Set an explicit, high-entropy SECRET_KEY for production and keep it stable. Back it up securely and use the same value on every server instance for the same Enfyra app. Changing or losing it invalidates existing auth tokens and prevents existing encrypted field values from decrypting.

Generate one before a production Docker deployment:

openssl rand -hex 32

Auth (Optional)

  • SALT_ROUNDS: bcrypt salt rounds (default: 10)
  • ACCESS_TOKEN_EXP: Access token expiration (default: 15m)
  • REFRESH_TOKEN_NO_REMEMBER_EXP: Refresh token expiration without remember (default: 1d)
  • REFRESH_TOKEN_REMEMBER_EXP: Refresh token expiration with remember (default: 7d)

Admin Account (Optional)

  • ADMIN_EMAIL: Default admin email (default: [email protected])
  • ADMIN_PASSWORD: Default admin password (default: 1234)

Example:

docker run -d \
  --name enfyra \
  -p 3000:3000 \
  -e [email protected] \
  -e ADMIN_PASSWORD=secure_password_123 \
  -v enfyra-data:/app/data \
  enfyra/enfyra:latest

App

  • ENFYRA_APP_PORT: App port (default: 3000)
  • API_URL: Backend API URL the Nuxt app calls (automatically set if ENFYRA_MODE=all)

Environment

  • NODE_ENV: Environment development, production, or test (default: production)

Tips

  1. Data persistence: Always use volume to persist data: bash -v enfyra-data:/app/data

  2. Production: Recommended to use external DB and Redis for production

  3. Development: Can use embedded services for quick testing

  4. Port Conflict:

  5. Container will automatically check port before starting embedded services
  6. If port is already in use, will show warning but continue
  7. Solution: Set REDIS_URI or DB_HOST to use external service

  8. Note: If using --network host, port conflict may occur with host

  9. Connect to Embedded Database from DBeaver/External Tools:

PostgreSQL (port 5432): bash docker run -d \ --name enfyra \ -p 3000:3000 \ -p 5432:5432 \ # ← Expose PostgreSQL port -v enfyra-data:/app/data \ enfyra/enfyra:latest

Then connect with DBeaver: - Host: localhost - Port: 5432 - Database: enfyra - Username: enfyra - Password: enfyra_password_123

MySQL (port 3306): bash docker run -d \ --name enfyra \ -p 3000:3000 \ -p 3306:3306 \ # ← Expose MySQL port -e EMBEDDED_DB=mysql \ -v enfyra-data:/app/data \ enfyra/enfyra:latest

Then connect with DBeaver: - Host: localhost - Port: 3306 - Database: enfyra - Username: enfyra - Password: enfyra_password_123

Redis (port 6379): bash docker run -d \ --name enfyra \ -p 3000:3000 \ -p 6379:6379 \ # ← Expose Redis port -v enfyra-data:/app/data \ enfyra/enfyra:latest

Default Admin User (auto-created on init): - Email: [email protected] - Password: 1234

  1. Logs: View logs for each service: bash docker exec enfyra cat /var/log/supervisor/server.log docker exec enfyra cat /var/log/supervisor/app.log docker exec enfyra cat /var/log/supervisor/redis.log docker exec enfyra cat /var/log/supervisor/postgres.log

Troubleshooting

Port Conflict Warning

If you see a warning about port conflict:

  WARNING: Port 6379 is already in use!
   This may cause conflicts when starting embedded Redis.

Solutions: 1. Use external service (recommended): bash -e REDIS_URI=redis://your-redis-host:6379/0 -e DB_URI=postgresql://user:pass@your-db-host:5432/dbname

  1. Stop service on host (if not needed): ```bash # Stop local Redis sudo systemctl stop redis

# Stop local PostgreSQL sudo systemctl stop postgresql ```

  1. Use different port (not recommended, as embedded services use fixed ports):
  2. Should use external service instead of changing port