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.

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:

Use .sh scripts on Linux/macOS and .cmd scripts on Windows.

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.

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.

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.