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
- Sign in and create a project with a name and key.
- Add members and confirm their access to the project.
- Create a requirement or task with an assignee, priority, and due date.
- 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.