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.

• Data-driven forecasts — delivery predictions from your team’s historical throughput. Know the probability of hitting any given date.
• Self-hosted — your delivery data stays on your infrastructure. Nothing is sent anywhere.
• Browser-based — no desktop software to install.

Deploying Shipcast for a team, on infrastructure you manage? The steps below set it up on one machine and are all most people need. If you are running it as a service for other people — your own PostgreSQL, a TLS proxy, a platform that provisions its own secrets — read ADMIN.md instead.

Setup

Before you start

You need Git and a container engine (Docker or Podman), and this repository cloned. If you do not have those yet, the installation guide is the fastest way to get them.

You also need the access token issued with your license — the configuration wizard asks for it.

Any recent laptop or desktop is enough: 2 CPU cores, 2 GB of free memory and 20 GB of disk handle plans of a few hundred deliverables. For larger plans, or a server shared by a team, see Sizing the server.

1. Go to the Shipcast directory

cd shipcast

2. Configure

./init_shipcast.sh      # Linux/macOS
.\init_shipcast.cmd     # Windows

The wizard asks for your access token, a database password (type generate for a secure random one), and the port to use. Press Enter to accept any value it offers. Re-run it any time to change something.

Prefer to edit by hand? Copy .env.example to .env instead.

3. Start

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

This signs in to the image registry, downloads the images, and starts everything. The first run takes a few minutes; later ones are quick.

4. Open Shipcast

Go to http://localhost:3456 — or whichever port you chose.

5. Create your account

The first time you open Shipcast there are no users yet, so it takes you straight to a setup page. Enter your name, email, and a password. That account is the administrator: it can add other users later, from Admin → Users.

If you are not redirected automatically, go to /setup directly — for example http://localhost:3456/setup.

6. Install your license

Shipcast runs without a license, but simulations will not run until one is installed — so this step is not optional in practice.

Your license may be tied to this specific installation, and the identifier it is tied to is created when Shipcast first starts. So the order matters:

1. With Shipcast running, open Admin → License (/admin/license). It shows the deployment ID of this installation.
2. Send that ID to your license provider.
3. Upload the license file you receive back, on that same page.

The page then reports Valid, along with the expiry date and which features your license includes.

Everyday commands

Run these from the shipcast directory. On Windows, use .\run_shipcast.cmd in place of ./run_shipcast.sh — the commands themselves are identical.

Three scripts ship with Shipcast:

On Windows, use the .cmd files. Stock Windows refuses to run .ps1 scripts and opens them in Notepad instead; each .cmd hands the matching script to PowerShell with that restriction lifted for that one launch, changing no setting on your machine. One spelling differs: ask for help as run_shipcast.cmd help, because PowerShell rejects --help before the script sees it. Everything else is spelled the same on every platform.

Updating

Restarting picks up the newest images automatically:

./run_shipcast.sh

To see what is available, run ./run_shipcast.sh tags. To stay on a particular version, set IMAGE_TAG in .env (or re-run the wizard) and restart:

latest is the default and right for most installations. Your data is upgraded automatically when Shipcast starts, so there is nothing else to do.

test still works and is identical to main, but it is deprecated — it was named after our test environment rather than after what it gives you. Switch to main at your convenience.

Your data

Everything you create — users, simulations, forecasts, your license — lives in a database stored in a container volume named fmb-shipcast-db-data. It survives restarts, upgrades and reboots.

./run_shipcast.sh clean permanently deletes it. Two things do not come back afterwards:

• all of your simulations and user accounts, and
• your license, if it is tied to this installation — a clean start creates a new deployment ID, and the old license no longer matches it. You would need it re-issued.

So treat clean as a last resort, not as a way to restart something. To just restart, use stop then start again.

Changing DB_NAME after the first run has the same effect as a rename with no data: Shipcast stops with Database "…" does not exist and tells you the exact command that would create it. Change it only if you mean to start a second, empty Shipcast.

Configuration

The wizard writes these to .env. Re-run ./init_shipcast.sh any time to change them.

Two of these are worth understanding before you change them:

• FRONTEND_HOST. The default keeps Shipcast reachable only from this machine. Setting 0.0.0.0 opens it to your network over plain HTTP, which means passwords cross that network unencrypted. If other people need to reach it, put it behind HTTPS — see ADMIN.md.
• SHIPCAST_SECRETS_KEY. The wizard generates this for you and you never need to touch it. It encrypts the Jira and Azure DevOps credentials you enter in the app, so changing it makes those unreadable and every tracker connection has to be set up again. Keep a copy wherever you keep passwords.

Registries

The same images, byte for byte, are published to two registries. Use the one your access was issued for; switching is a matter of these three lines in .env (or re-running the wizard), followed by a restart:

GitHub does not accept fine-grained tokens for its container registry; create a classic one at https://github.com/settings/tokens. Your data is not affected by switching: it lives in the database volume, not in the images.

Passwords you set by hand must use only letters, digits, and . _ ~ -. Other characters ($, `, /, @, :, ', ") break the connection string. Typing generate in the wizard always produces a safe one.

Troubleshooting

Locked out

If the administrator password is lost, reset the accounts and create a new one. Your simulations and license are not touched:

docker exec -it fmb-shipcast-api api admin reset --force
./run_shipcast.sh

Then open Shipcast again and complete the setup page as in step 5 of Setup. Note this removes all administrator accounts, so whoever completes setup next becomes the administrator.

Podman network errors (WSL or corporate machines)

Errors like netavark: nftables error or Could not process rule: No such file or directory come from restricted network access, not from Shipcast. Switch Podman to a different networking mode:

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

podman system reset --force

If pasta is unavailable, use slirp4netns in its place. On Windows, Docker Desktop avoids this class of problem entirely.

Running Shipcast for a team

Everything above assumes one machine, set up by the person who uses it. If you are deploying Shipcast as a service — your own PostgreSQL server, HTTPS, secrets from a vault, Kubernetes, backups — ADMIN.md covers the deployment contract, the database requirements, TLS and reverse-proxy setup, backups, and upgrades.

Support

Contact your license provider for support, access tokens, and product inquiries.