Shipcast

Forecast delivery dates with confidence. Make promises you can keep.

Shipcast is a self-hosted forecasting and analytics service that brings Monte Carlo simulations to your delivery pipeline. Stop guessing when work will be done. Start showing stakeholders probabilistic forecasts backed by your team’s actual performance data.

Why Shipcast?

• Data-Driven Forecasts - Generate delivery predictions using Monte Carlo simulations based on your team’s historical throughput. Know the probability of hitting any given date.

• Self-Hosted Privacy - Your delivery data stays on your infrastructure. The entire stack runs in Docker containers on your own servers.

• Modern Web Interface - Access forecasts and analytics through an intuitive browser-based dashboard. No desktop software to install.

• Production-Ready Architecture - Built with a robust Rust backend, PostgreSQL database, and nginx frontend. Designed for reliability.

Quick Start

Prerequisites

Before continuing, ensure you have completed the following from the main installation guide:

1. Git installed and configured
2. Docker or Podman installed and running
3. Repository cloned via git clone

If you haven’t completed these steps, return to the main page and follow the Requirements and Getting Started sections first.

Step 1. Navigate to Shipcast Directory

cd shipcast

Step 2. Configure Environment

Run the interactive configuration wizard:

# Linux/macOS
./init_shipcast.sh

# Windows
.\init_shipcast.cmd

This guides you through all settings. Type generate when prompted for password to create a secure random one.

Alternative (manual setup): Copy .env.example to .env and edit manually.

Step 3. Start Services

# Linux/macOS
./run_shipcast.sh

# Windows
.\run_shipcast.cmd

The script authenticates with the container registry, pulls images, and starts all services.

Why .cmd and not .ps1 on Windows? Stock Windows refuses to run .ps1 files (running scripts is disabled on this system) and opens them in Notepad when double-clicked. Each .ps1 here has a .cmd launcher beside it that hands the same script to PowerShell with -ExecutionPolicy Bypass for that launch only — it changes no setting on your machine, and it forwards whatever command you pass. So you never have to touch execution policy, and the commands match the Linux and macOS ones (with one exception, --help, noted under Scripts Reference). Prefer the .ps1 directly? It works unchanged in a PowerShell window where scripts are allowed (5.1+); if yours blocks them, run powershell -ExecutionPolicy Bypass -File .\run_shipcast.ps1 [command], or ask your IT administrator to relax the policy.

Step 4. Access the Application

Open your browser to: http://localhost:3456

(Or the port you configured in FRONTEND_PORT)

Scripts Reference

Shipcast provides scripts for setup and operation:

Each Windows .cmd is a one-line launcher for the .ps1 of the same name, so no execution-policy change is needed and the commands are the same on every platform. The .ps1 scripts remain callable directly on PowerShell 5.1+ where policy allows it.

One spelling differs. PowerShell reads a leading -- as a parameter name, so --help and -h are rejected before the script sees them (A parameter cannot be found that matches parameter name '-help'). On Windows ask for help as run_shipcast.cmd help or run_shipcast.cmd /?. Every other command is spelled identically on both platforms. This is a property of the PowerShell runner itself, not of the .cmd launcher — calling the .ps1 directly behaves the same way.

init_shipcast - Configuration Wizard

Run once to create or update your .env configuration file.

# Linux/macOS
./init_shipcast.sh

# Windows
.\init_shipcast.cmd

The wizard guides you through:

• Registry authentication - Enter your GitLab access token
• Container images - Set registry URL and version tag
• Database - Configure credentials (type generate for a random password)
• Frontend access - Set host binding and port
• Application settings - Configure log level
• Container runtime - Choose Docker or Podman

Press Enter to keep existing values when updating configuration.

run_shipcast - Service Management

Manage the Shipcast containers after configuration.

# Linux/macOS
./run_shipcast.sh [command]

# Windows
.\run_shipcast.cmd [command]

Examples:

./run_shipcast.sh              # Start or reload services
./run_shipcast.sh logs         # Watch live logs (Ctrl+C to exit)
./run_shipcast.sh status       # Check if services are running
./run_shipcast.sh tags         # See available versions
./run_shipcast.sh stop         # Stop services (asks for confirmation)

run_shipcast_test - Test Environment

Wrapper script that runs Shipcast with:

• IMAGE_TAG=test - Uses the test image version
• DB_NAME=shipcast_test - Uses a separate database

All other settings are loaded from your .env file.

# Linux/macOS
./run_shipcast_test.sh

# Windows
.\run_shipcast_test.cmd

Supports all the same commands as run_shipcast:

./run_shipcast_test.sh logs    # View test environment logs
./run_shipcast_test.sh stop    # Stop test environment

Architecture

                    +------------------+
    Port 3456 ----> |    Frontend      | (nginx)
                    |  /api/* proxy    |
                    +--------+---------+
                             |
                    +--------v---------+
                    |       API        | (Rust)
                    +--------+---------+
                             |
                    +--------v---------+
                    |    PostgreSQL    |
                    +------------------+

• Frontend - nginx serving the web UI, proxies API requests to the backend
• API - High-performance Rust backend service
• Database - PostgreSQL for persistent storage

Only the frontend port is exposed to the host. All internal communication happens on an isolated Docker network.

Database Prerequisites

Shipcast does not create its database. It never issues CREATE DATABASE, CREATE ROLE, or CREATE EXTENSION — at startup it verifies its preconditions and, if any is unmet, exits with a message naming the failed precondition and the exact SQL to fix it (see Startup failures below).

With the bundled stack (the default), provisioning is handled for you: the db service creates the database named by DB_NAME when it first boots on an empty data volume. Nothing to do — but read Renaming the database before ever changing DB_NAME.

With an external or managed PostgreSQL (Amazon RDS, Azure Database, a shared corporate cluster), provisioning is your job. Shipcast requires:

Minimal provisioning, as a cluster administrator:

CREATE ROLE shipcast WITH LOGIN PASSWORD 'change-me';
CREATE DATABASE shipcast OWNER shipcast;

PostgreSQL 15+ note. Since version 15, schema public no longer grants CREATE to PUBLIC. A role that owns the database (as in the recipe above) has the required privileges implicitly. A role that does not own it — common on shared clusters and some managed providers — needs an explicit grant:

GRANT USAGE, CREATE ON SCHEMA public TO "shipcast";

To point the stack at an external server, edit the DATABASE_URL value in docker-compose.yml’s api service (the shipped value is fixed to the internal db container) and remove or ignore the db service.

Shipcast’s side of the contract: it owns the schema via forward-only migrations, run automatically at startup. It is the sole writer — do not hand-edit the schema, and do not share the database with another application.

Startup failures

Startup failures name the precondition they violated:

The authoritative version of this contract lives in the Shipcast source repository (docs/database-setup.md, access provided with your license).

Configuration Reference

All variables are required. Run ./init_shipcast.sh (or .\init_shipcast.cmd on Windows) for guided setup. You can re-run it anytime to update settings.

Data Persistence

Database data is stored in a Docker volume named fmb-shipcast-db-data. This persists across container restarts.

To completely reset the database (requires confirmation):

./run_shipcast.sh clean      # Linux/macOS
.\run_shipcast.cmd clean     # Windows

Warning: This permanently deletes all data.

Renaming the Database

The db service creates the database named by DB_NAME only on first boot, when the data volume is empty. Changing DB_NAME in .env after the volume exists does not create the new database — Shipcast fails fast at startup with Database "X" does not exist, plus the CREATE DATABASE statement that would fix it. (Older versions silently started a fresh empty database instead, which looked like total data loss.)

To rename, either create the new database yourself inside the running db container:

docker exec -it fmb-shipcast-db psql -U $DB_USER -c 'CREATE DATABASE "newname" OWNER "youruser";'

or start over from a clean volume with ./run_shipcast.sh clean (deletes all data).

Updating

To update to the latest version, simply restart the services:

./run_shipcast.sh up

This automatically pulls the latest images before starting.

Switching Versions

List available versions:

./run_shipcast.sh tags

To use a specific version, either:

Option A: Re-run the init script and enter the desired tag:

./init_shipcast.sh

Option B: Edit .env directly:

IMAGE_TAG=2026-01-29T12-31-53Z-071c9bc

Then restart: ./run_shipcast.sh up

Troubleshooting

For manual registry login troubleshooting:

docker login registry.gitlab.com

Podman Network Errors (WSL / Corporate Environments)

If you see errors like netavark: nftables error or Could not process rule: No such file or directory, this is typically caused by restricted network/firewall access in WSL or corporate environments.

Solution: Switch Podman to use pasta or slirp4netns networking:

mkdir -p ~/.config/containers
cat > ~/.config/containers/containers.conf << 'EOF'
[network]
default_rootless_network_cmd = "pasta"
EOF

podman system reset --force

If pasta is not available, try slirp4netns:

cat > ~/.config/containers/containers.conf << 'EOF'
[network]
default_rootless_network_cmd = "slirp4netns"
EOF

podman system reset --force

Alternative: Use Docker Desktop on Windows instead of Podman in WSL, as it handles networking differently and avoids these issues.