Installation

Installation#

How to install FERRY for evaluation or production use.

Prerequisites#

Requirement

Version

Purpose

Git

any

Clone the repository

Multipass

latest

Linux VM for FERRY services (recommended on macOS)

OrbStack

latest

Alternative VM provider (macOS only)

Make

any

Convenience wrapper for installation commands

mkcert

latest

Trusted local HTTPS certificates

mkcert is required only for local HTTPS. Install it before running make install:

brew install mkcert

No other host dependencies are required. Python, Node.js, PostgreSQL, and Redis all run inside the platform environment.

Installation targets#

FERRY supports two installation modes:

OrbStack VM (alternative)#

Uses OrbStack to create a Linux VM. Available on macOS only. Use this target when you prefer OrbStack over Multipass.

Prerequisites: OrbStack must be installed.

make install TARGET=orbstack

The installation lifecycle#

make install performs these steps:

  1. Create VM — provisions the Linux VM if it does not already exist.

  2. Generate .env — creates the configuration file with secure defaults if one does not exist. Existing .env is preserved across re-installation.

  3. Build images — builds the Docker images for frontend, backend, worker, and supporting services.

  4. Start services — starts all containers: reverse proxy, frontend, backend, PostgreSQL, Redis, worker.

  5. Apply migrations — runs Alembic database migrations to bring the schema up to date.

  6. Seed institutional state — registers execution environments and data resources from manifests, seeds the auth framework (roles, capabilities), and creates the administrator account.

  7. Health check — verifies all services are operational.

After installation, the platform is running and accessible at https://localhost.

Administrator credentials#

The administrator account is created during installation with these defaults:

Field

Value

Email

admin@ferry.local

Password

Stored in .env as ADMIN_PASSWORD

The password is generated automatically and saved to .env. It is never displayed in the terminal. To retrieve it:

grep ADMIN_PASSWORD .env

For evaluation environments, you can create additional accounts:

make seed-demo

This creates three evaluation persona accounts (researcher, moderator, maintainer) and prints their credentials. See the Quick Start for the guided tutorial.

Configuration file#

.env is created automatically at the repository root. It contains:

Variable

Purpose

Generated

ADMIN_PASSWORD

Administrator account password

Yes, if not set

POSTGRES_PASSWORD

Database credential

Yes

REDIS_PASSWORD

Redis credential

Yes

SECRET_KEY

Application signing key (min 32 chars)

Yes, if not set

PUBLIC_URL

Canonical external URL

Default: https://localhost

SMTP_HOST

SMTP relay for email notifications

Optional

SMTP_PORT

SMTP port

Default: 587

SMTP_USER

SMTP username

Optional

SMTP_PASSWORD

SMTP password

Optional

SMTP_USE_TLS

TLS for SMTP

Default: true

To regenerate all secrets, delete .env and run make install again.

Public URL#

PUBLIC_URL is the canonical external URL for the FERRY installation. It is used in email notification links and browser-facing redirects.

For local evaluation, the default (https://localhost) works. For production deployments, set this to the institution’s domain:

PUBLIC_URL=https://ferry.institution.edu

Local HTTPS#

FERRY requires HTTPS for secure cookie-based sessions. During local evaluation, trusted HTTPS certificates are generated automatically using mkcert.

To regenerate certificates:

make certs

This is also useful if certificates expire or if you need to trust them on a new machine.

Uninstalling#

To remove the local FERRY installation:

make uninstall

This stops the platform, deletes the VM (OrbStack, Multipass) or tears down Docker resources, and preserves the repository and .env. To fully reset:

rm .env
make uninstall

Then reinstall with make install.

Next steps#

Contents