DocumentationQuick start

Quick start

Start Feronavi with prebuilt GHCR images and create an organization and administrator account.

Prepare your environment

You need Docker 24 or later and Docker Compose v2. The default images are pulled from GitHub Container Registry; Node.js, pnpm, and a local build are not required. For evaluation, allow at least 2 CPU cores, 4 GB of memory, and 40 GB of free disk space. Plan production storage around database and attachment growth.

The default images are ghcr.io/feronavi/feronavi-app and ghcr.io/feronavi/feronavi-db. The app provides 0.1.0 and latest tags; the database image uses PostgreSQL 16 tag 16. For production, pin the app version by setting FERONAVI_VERSION=0.1.0 in .env.

Get the deployment file

Download compose.yaml from the product repository into a dedicated deployment directory, or run:

mkdir feronavi-deploy && cd feronavi-deploy && \
  curl -fL https://raw.githubusercontent.com/JasperPengC/feronavi/main/compose.yaml -o compose.yaml

This creates a directory and downloads the deployment configuration from main. Run the remaining commands from this directory. For an existing deployment, use its directory and preserve the current configuration.

Create a database password

Create a local .env with a random password. This command preserves an existing .env file.

(umask 077; test -e .env || echo "DB_PASSWORD=$(openssl rand -hex 24)" > .env)

If .env already exists, confirm that it contains a nonempty DB_PASSWORD. Keep this file out of version control and public websites.

Pull and start

Pull the prebuilt images and start the services:

docker compose pull
docker compose up -d --wait
docker compose ps

The stack includes the application, background worker, database, and cache. Wait for the services to become healthy before continuing. To build development images from source, use the compose.source.yaml override.

Complete setup

On the server itself, open http://127.0.0.1:3000/setup and follow the wizard to create your organization and administrator.

The default service binds to the loopback interface. For a remote server, create an SSH tunnel first:

ssh -L 3000:127.0.0.1:3000 your-user@your-server

Keep the terminal connected and open http://127.0.0.1:3000/setup in your local browser. Replace the sample user and server with your actual SSH details.

Create your first work item

  1. Sign in and create a project with a name and key.
  2. Add members and confirm their access to the project.
  3. Create a requirement or task with an assignee, priority, and due date.
  4. Update the task status on the board and record decisions in project documents.

Continue with projects and planning. Before opening access to your team, configure HTTPS, a reverse proxy, and backups in production deployment.

Inspect startup logs

docker compose logs --tail=100 app worker

For database connection failures, check .env and service health first. If an image pull fails, check GitHub Container Registry access and the image tag.

Type a keyword to search all documentation.