Self-hosted package tracking platform with scriptable carrier logic — built on Selenium for flexible, reliable automation.
- Selenium-based tracking with configurable step sequences
- Scriptable extraction logic using Jint and HTML Agility Pack
- Regex-driven status rules for mapping carrier messages to statuses
- Per-carrier execution history, including logs and downloadable artifacts
- Dashboard view for tracking package statuses at a glance
- Email notifications (SMTP) for out-for-delivery and delivered updates
- Docker-first deployment via a single
compose.ymlfile - User and role management backed by an access control list
Shipyard is comprised of three components, each with a different role.
The web UI (port 7447) is your primary window into the application. Designed as a progressive web app, this component gives you controls for tracking your existing packages, adding new ones, and configuring carriers.
The API (port 7448), provides access to the application's data. Built in OData style, its endpoints support filtering and sorting, in addition to standard CRUD operations. The web UI communicates directly with the API.
The background worker (headless) is not accessible directly. It communicates with the API via a message bus and uses the bus internally for retries on failure. The worker executes carrier steps, extracts tracking data, and publishes tracking results.
- Download the
compose.ymlfile. - Run
docker compose -f compose.yml up -dto pull and run the application stack. - Access the application in a browser at http://localhost:7447, or your configured
SHIPYARD_API_HOST(default admin:admin/password). - (Optional) Run
docker compose -f compose.yml downto stop and remove the application stack.
Note
Running docker compose down deletes the containers and all of their data, except the data stored in volumes. By default, Shipyard will persist data in its database to a volume. While running a subsequent docker compose up will re-create the application, the original database data will be retained.
Settings can be configured by adjusting values in the compose.yml file or by creating a .env file, located in the same directory as the compose.yml file.
Values in .env will override those in compose.yml.
| Setting | Description | Default |
|---|---|---|
| POSTGRES_DB | The name of the PostgreSQL database. | shipyard |
| POSTGRES_USER | The name of the PostgreSQL user. | shipyard |
| POSTGRES_PASSWORD | The password of the PostgreSQL user. | mySecure(!)Password |
| RABBITMQ_USER | The name of the RabbitMQ user. | shipyard |
| RABBITMQ_PASSWORD | The password of the RabbitMQ user. | mySecure(!)Password |
| SHIPYARD_BOOTSTRAP_USER | The username of the default user to create. | admin |
| SHIPYARD_BOOTSTRAP_PASSWORD | The password of the default user to create. | password |
| SHIPYARD_USE_PROXY | Whether Shipyard is behind a reverse proxy. | false |
| SHIPYARD_API_HOST | The base URL hosting Shipyard. | http://localhost:7448 |
| SHIPYARD_API_PORT | The port on which to run the Shipyard API. | 7448 |
| SHIPYARD_WEB_HOST | The base URL hosting Shipyard UI. | http://localhost:7447 |
| SHIPYARD_WEB_PORT | The port on which to run the Shipyard UI. | 7447 |
| SHIPYARD_DEFAULT_TZ | The default IANA time zone for the app. | America/Chicago |
| SHIPYARD_ENC_TYPE | How to load the encryption certificate: File or Text | File |
| SHIPYARD_ENC_PATH | If File, the path to the encryption certificate | /opt/certificates/auth-encryption.pfx |
| SHIPYARD_ENC_CRT | TEMP; if Text, encryption public key (.crt) | (a certificate) |
| SHIPYARD_ENC_KEY | TEMP; if Text, encryption private key (.key) | (a certificate) |
| SHIPYARD_SIGN_TYPE | How to load the signing certificate: File or Text | File |
| SHIPYARD_SIGN_PATH | If File, the path to the encryption certificate | /opt/certificates/auth-signing.pfx |
| SHIPYARD_SIGN_CRT | TEMP; if Text, signing public key (.crt) | (a certificate) |
| SHIPYARD_SIGN_KEY | TEMP; if Text, signing private key (.key) | (a certificate) |
Warning
The SHIPYARD_ENC_CRT, SHIPYARD_ENC_KEY, SHIPYARD_SIGN_CRT, and SHIPYARD_SIGN_KEY environment variables are deprecated and will be removed in a future release.
If you created a custom certificate, merge it into a .pfx and move it to ./data/certificates to be prepared for the removal of these environment variables.
Shipyard does not currently manage HTTPS certificates internally. It is recommended to deploy Shipyard behind a reverse proxy such as nginx, Caddy, or Traefik to enable SSL.
If you use nginx, you can proxy the Web UI (port 7447) and API (port 7448) to serve them under your own domain with HTTPS enabled. Ensure the SHIPYARD_API_HOST is set to match your domain.
Shipyard is currently in Alpha. While it is functional and stable for personal use, breaking changes may occur between releases.
It is important to grab the latest compose.yml file when updating to a new version.
This application is licensed under the Apache License 2.0.