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

1. Navigate to ShipCast Directory

cd shipcast

2. Configure Environment

cp .env.example .env

Edit .env and set:

ACCESS_TOKEN - Your GitLab registry access token (provided with your license)
POSTGRES_PASSWORD - A secure password for the database

3. Start Services

Linux/macOS:

./run_shipcast.sh

Windows:

run_shipcast.cmd

The script will authenticate with the container registry, pull the latest images, and start all services.

4. Access the Application

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

(Or the port you configured in FRONTEND_PORT)

Commands

Use ./run_shipcast.sh on Linux/macOS or run_shipcast.cmd on Windows.

Command	Description
(default)	Start all services
`up`	Start all services
`down`	Stop all services
`restart`	Restart all services
`status`	Show service status
`logs`	View logs (follow mode)
`pull`	Pull latest images
`clean`	Stop and remove all data

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

Variable	Default	Description
`ACCESS_TOKEN`	(required)	GitLab registry access token
`POSTGRES_USER`	`postgres`	Database username
`POSTGRES_PASSWORD`	(required)	Database password
`POSTGRES_DB`	`shipcast`	Database name
`FRONTEND_PORT`	`3456`	Port to access the web UI
`IMAGE_TAG`	`latest`	Version tag for container images
`RUST_LOG`	`info`	API log level (error/warn/info/debug/trace)
`CONTAINER_RUNTIME`	auto-detect	Force docker or podman

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:

./run_shipcast.sh clean

Warning: This permanently deletes all data.

Updating

To update to the latest version:

./run_shipcast.sh restart

Or to update to a specific version, set IMAGE_TAG in .env:

IMAGE_TAG=1.2.0

Then restart the services.

Troubleshooting

Issue	Solution
Cannot pull images	Verify `ACCESS_TOKEN` in `.env` has `read_registry` scope
Services not starting	Check Docker is running with `docker info`, then view logs with `./run_shipcast.sh logs`
Port already in use	Change `FRONTEND_PORT` in `.env` to an available port
Database connection issues	Ensure database container is healthy with `./run_shipcast.sh status`

For manual registry login troubleshooting:

docker login registry.gitlab.com