Installation¶

Requirements¶

Docker with Compose plugin
Git
No API keys required to get started

One-line install¶

bash <(curl -fsSL https://git.opensourcesolarpunk.com/Circuit-Forge/snipe/raw/branch/main/install.sh)

This clones the repo to ~/snipe and starts the stack. Open http://localhost:8509 when it completes.

Manual install¶

Snipe's API image is built from a context that includes circuitforge-core. Both repos must sit as siblings:

workspace/
├── snipe/               ← this repo
└── circuitforge-core/   ← required sibling

mkdir snipe-workspace && cd snipe-workspace
git clone https://git.opensourcesolarpunk.com/Circuit-Forge/snipe.git
git clone https://git.opensourcesolarpunk.com/Circuit-Forge/circuitforge-core.git
cd snipe
cp .env.example .env
./manage.sh start

Managing the stack¶

./manage.sh start     # build and start all containers
./manage.sh stop      # stop containers
./manage.sh restart   # rebuild and restart
./manage.sh status    # container health
./manage.sh logs      # tail logs
./manage.sh open      # open in browser

Updating¶

git pull
./manage.sh restart

Ports¶

Service	Default port
Web UI	8509
API	8510

Both ports are configurable in .env.

No-Docker install (bare metal)¶

Run install.sh --bare-metal to skip Docker and install via conda or venv instead. This sets up the Python environment, builds the Vue frontend, and writes helper scripts.

Requirements: Python 3.11+, Node.js 20+, xvfb (for the eBay scraper).

bash <(curl -fsSL https://git.opensourcesolarpunk.com/Circuit-Forge/snipe/raw/branch/main/install.sh) --bare-metal

After install, you get two scripts:

Script	What it does
`./start-local.sh`	Start the FastAPI API on port 8510
`./serve-ui.sh`	Serve the built frontend with `python3 -m http.server 8509` (dev only)

serve-ui.sh is single-threaded and suitable for testing only. For a real deployment, use nginx.

nginx config (production bare-metal)¶

Install nginx, copy the sample config, and reload:

sudo cp docs/nginx-self-hosted.conf /etc/nginx/sites-available/snipe
sudo ln -s /etc/nginx/sites-available/snipe /etc/nginx/sites-enabled/snipe
# Edit the file — update `root` to your actual web/dist path
sudo nginx -t && sudo systemctl reload nginx

See docs/nginx-self-hosted.conf for the full config with TLS notes.

Chromium / Xvfb note¶

Snipe uses headed Chromium via Xvfb to bypass Kasada (the anti-bot layer on eBay seller profile pages). If Chromium is not detected, the scraper falls back to the eBay Browse API — add EBAY_APP_ID / EBAY_CERT_ID to .env so that fallback has credentials.

The installer detects and installs Xvfb automatically on Debian/Ubuntu/Fedora. Chromium is installed via playwright install chromium. macOS is not supported for the scraper path.