heyfworld/ferdium-server

•Updated 4 months ago

Image

331

heyfworld/ferdium-server repository overview

⁠Modernized Ferdium Server

An optimized, modernized, and lightweight self-hostable Docker image for the Ferdium⁠ app client, built on Node.js 24 LTS and AdonisJS v5.

This is a drop-in replacement for the official legacy ferdium/ferdium-server image, optimized for homelabs and personal hosting.

⁠What It Does & Key Enhancements

Modern Tech Stack: Built on Node.js 24.16.0 LTS (Alpine) and pnpm v10.
Optimized Footprint: Multi-stage build with selective artifact copying to keep the runtime image size under ~120MB (saving over 60% compared to upstream).
Auto-Recipe Compiler: Automatically pulls, compiles, and packages the latest Ferdium recipe library on first startup without engine mismatch issues.
Enhanced Security: Automatic secure APP_KEY generation and JWT certificate generation at startup.
Health Checks: Built-in health check route that verifies both API responsiveness and database connectivity.

⁠Quick Start

⁠With docker-compose (recommended)

# docker-compose.yml
services:
  ferdium-server:
    image: heyfworld/ferdium-server:latest
    container_name: ferdium-server
    ports:
      - "3333:3333"
    environment:
      - NODE_ENV=production
      - APP_URL=http://localhost:3333
      - DB_CONNECTION=sqlite
      - DATA_DIR=/data
      - JWT_USE_PEM=true
      - IS_REGISTRATION_ENABLED=true
      - IS_DASHBOARD_ENABLED=true
    volumes:
      - ./data/ferdium:/data
      - ./data/recipes:/app/recipes
    restart: unless-stopped

Copy

docker compose up -d

Copy

⁠Or with `docker run`:

docker run -d \
  --name ferdium-server \
  --restart unless-stopped \
  -p 3333:3333 \
  -e NODE_ENV=production \
  -e APP_URL=http://localhost:3333 \
  -e DB_CONNECTION=sqlite \
  -e DATA_DIR=/data \
  -e JWT_USE_PEM=true \
  -v $(pwd)/data/ferdium:/data \
  -v $(pwd)/data/recipes:/app/recipes \
  heyfworld/ferdium-server:latest

Copy

Open http://localhost:3333 — done.

⁠Environment Variables

Variable	Default	Description
`APP_URL`	`http://localhost:3333`	The external URL used to access the server
`DB_CONNECTION`	`sqlite`	Database driver (`sqlite`, `pg`, `mysql`)
`DATA_DIR`	`/data`	Directory where certificates and keys are stored
`JWT_USE_PEM`	`true`	Generate/use RSA key pair PEM files for JWT auth
`IS_REGISTRATION_ENABLED`	`true`	Allow new user registration
`IS_DASHBOARD_ENABLED`	`true`	Enable web dashboard
`CONNECT_WITH_FRANZ`	`false`	Enable integration/account import from Franz

Note: For external databases, configure standard credentials (DB_HOST, DB_PORT, DB_USER, DB_PASSWORD, DB_DATABASE).

⁠Advanced Configuration

For specialized deployments, you can tune the following advanced variables:

⁠Database Tuning & SSL

Variable	Default	Description
`DB_SSL`	`false`	Enable SSL for database connections (e.g., PostgreSQL). Set `true` if hosted on cloud platforms.
`DB_CA_CERT`	None	CA certificate string for verifying secure database connections (overrides `DB_SSL` configuration if provided).
`DB_DEBUG`	`false`	Enable verbose database query logging for debugging.
`DB_SQLITE_JOURNAL_MODE`	`WAL`	SQLite journal mode (`DELETE`, `TRUNCATE`, `PERSIST`, `MEMORY`, `WAL`, `OFF`).
`DB_SQLITE_SYNCHRONOUS`	`FULL`	SQLite synchronous mode (`OFF`, `NORMAL`, `FULL`, `EXTRA`).
`DB_BUSY_TIMEOUT`	`5000`	SQLite busy timeout in milliseconds before a query fails.

⁠JWT Authentication

Variable	Default	Description
`JWT_EXPIRY`	`90d`	JWT Token expiration duration (e.g., `90d`, `24h`, `7d`).
`JWT_PUBLIC_KEY`	None	Override path or inline RSA public key PEM string.
`JWT_PRIVATE_KEY`	None	Override path or inline RSA private key PEM string.

⁠Mail Service Settings

Variable	Default	Description
`MAIL_CONNECTION`	`smtp`	Mailer driver: `smtp`, `ses`, `mailgun`, `sparkpost`.
`MAIL_REQUIRE_TLS`	`false`	Force TLS encryption for SMTP connections.
`MAIL_SSL`	`false`	Enable SSL for SMTP connections.
`SES_ACCESS_KEY`	None	AWS SES Access Key ID.
`SES_ACCESS_SECRET`	None	AWS SES Access Secret Key.
`SES_REGION`	None	AWS SES Region (e.g., `us-east-1`).
`MAILGUN_API_KEY`	None	Mailgun API Private Key.
`MAILGUN_DOMAIN`	None	Mailgun Sending Domain name.
`SPARKPOST_API_KEY`	None	SparkPost API Transmit Key.

⁠Miscellaneous Configuration

Variable	Default	Description
`IS_CREATION_ENABLED`	`true`	Allow users to upload and package custom recipes.
`LOG_LEVEL`	`info`	Logging verbosity level (e.g., `trace`, `debug`, `info`, `warn`, `error`).
`APP_NAME`	`ferdium-server`	Customized name of the application instance.

⁠Verify

# Verify API and Database Health
curl -s http://localhost:3333/health

# Check server startup logs
docker logs ferdium-server

Tag summary

Recent tags

Content type

Image

Digest

sha256:88b30cb2a…

Size

117.9 MB

Last updated

4 months ago

docker pull heyfworld/ferdium-server