Parcels

A minimal package tracking app

Overview

A self-hosted package tracker for USPS. Track your packages without logging into USPS every time.

Single ~7MB Rust binary
Averages around ~10MB of RAM usage
Password authentication
Track USPS packages with custom labels
Delete packages you no longer want to track

Quickstart

git clone https://github.com/stevedylandev/andromeda.git
cd andromeda
cp apps/parcels/.env.example .env
# Edit .env with your USPS API credentials and app password
cargo run -p parcels

You'll need a USPS Web Tools API account to get your USPS_CLIENT_ID and USPS_CLIENT_SECRET.

Environment Variables

Variable	Description	Default
`APP_PASSWORD`	Password for login authentication	required
`PARCELS_DB_PATH`	SQLite database file path	`parcels.db`
`USPS_CLIENT_ID`	USPS OAuth2 client ID	required
`USPS_CLIENT_SECRET`	USPS OAuth2 client secret	required
`PORT`	Server port	`3000`
`COOKIE_SECURE`	Enable HTTPS-only cookies	`false`

Structure

parcels/
├── src/
│   ├── main.rs        # Axum web server, routes, and app state
│   ├── auth.rs        # Password verification and session management
│   ├── db.rs          # SQLite database layer (packages, events, sessions)
│   └── usps.rs        # USPS API integration with OAuth2 token caching
├── templates/         # Askama HTML templates
│   ├── base.html      # Base layout
│   ├── index.html     # Package list
│   ├── detail.html    # Package detail with tracking events
│   ├── add.html       # Add package form
│   └── login.html     # Login page
├── static/            # Fonts, favicons, and images
├── Dockerfile
└── docker-compose.yml

Deployment

Railway

Docker

cd apps/parcels
cp .env.example .env
# Edit .env with your credentials
docker compose up -d

This will start Parcels on port 3000 with a persistent volume for the SQLite database.

Binary

cargo build --release -p parcels

The resulting binary is self-contained (~7MB). Copy it to your server with a configured .env file and run it directly.