A community marketplace for buying, selling, and claiming Star Wars Unlimited singles.
apps/web: Next.js web application.apps/api: Node.js/Express API. It uses local SQLite in development and Turso/libSQL in production.packages/shared: shared TypeScript contracts.
Google sign-in is initiated in the browser and exchanged for a 30-day, renewable application session. The opaque session token is stored in a secure, HttpOnly cookie and only its hash is kept in the database.
- Install dependencies with
pnpm install. - Copy
apps/api/.env.exampletoapps/api/.envand configure the API variables. - Copy
apps/web/.env.exampletoapps/web/.env.localand configure the Google and S3 variables. Next.js does not load the repository-root.envbecause the web app runs fromapps/web. - Run
pnpm db:migrate. - Run
pnpm db:seedto download and import the current SWU card catalog. - To access the app from other devices on your local network, copy
.env.local.exampleto.env.localand setLOCAL_IPto this computer's local IP address. On macOS with Wi-Fi you can usually find it withipconfig getifaddr en0. - Run
pnpm devand openhttp://<LOCAL_IP>:4000.
db:seed downloads the public bulk export from SWU API and upserts cards in batches. Set
SWU_CARD_CATALOG_URL to use a compatible mirror or fixture instead.
To import test publications into the local SQLite database, edit
apps/api/seeds/local-listings.json and run pnpm db:seed:listings. You can also pass a different
JSON file after --, for example pnpm db:seed:listings -- ./seeds/my-listings.json. The command is
idempotent for listing IDs and refuses to run in production or against a non-file: database.
When the API is running outside production against a local file: database, the header includes a
local user selector populated from the users table. It can be used to switch between seller and
buyer accounts and exercise both sides of a claim without Google sign-in. This development login is
disabled automatically in production and for remote databases.
The web client runs on port 4000 and the API on port 4001 by default. Both listen on all network
interfaces in development; LOCAL_IP determines the URLs advertised to the browser and the API's
allowed CORS origin. Without .env.local, development continues to use localhost.
pnpm lintchecks ESLint rules for TypeScript, React, and React Hooks.pnpm formatformats the workspace with Prettier.pnpm checkruns linting, formatting checks, type checks, and tests.
The production web application is https://ackb.ar and its public API is
https://api.ackb.ar (health check: https://api.ackb.ar/health). The deployment host is private
configuration and is not stored in this repository.
Build the workspace with pnpm build, run the API with pnpm --filter @swu/api start, and run the web app with pnpm --filter @swu/web start. Set NEXT_PUBLIC_API_URL to the public API URL and WEB_ORIGIN to the public web URL. When they use different subdomains, set SESSION_COOKIE_DOMAIN to their shared parent domain (for example, .example.com). A process manager and reverse proxy can keep both services running behind HTTPS on a private server.
Photo uploads are resized in the browser to a maximum dimension of 1500 pixels and compressed to less than 1 MB before using presigned S3 POSTs to go directly to the bucket. JPG, PNG, WebP, AVIF, GIF, HEIC, and HEIF sources are supported; HEIC/HEIF photos are converted before compression. Configure S3_BUCKET, S3_REGION, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and S3_PUBLIC_URL in the API environment. The bucket must allow public reads (or be fronted by the public CDN in S3_PUBLIC_URL) and its CORS policy must allow POST from the web origin. Each publication supports up to 24 images, with source files of up to 20 MB each.
The API can use a persistent local SQLite file on a private server. Set DATABASE_URL to an absolute file URL such as file:/var/lib/swu/marketplace.db, or configure a remote libSQL database with DATABASE_AUTH_TOKEN.
To copy one local publication into another database, run pnpm --filter @swu/api db:import-listing -- --source local.db --listing <id> --owner-email <email>. This performs a dry run and resolves the target owner by email. Review the output and repeat with --confirm to write the publication, its items, and its images atomically. Run it with DATABASE_URL and, when needed, DATABASE_AUTH_TOKEN configured for the target database.
Pushes to main are verified and deployed to /home/deploy/ackbar-web as immutable releases. The
workflow expects the GitHub Actions secrets DEPLOY_HOST, SSH_KEY (the private key for the
deployment user), and KNOWN_HOSTS (generated with ssh-keyscan -H "$DEPLOY_HOST"). Protect the
production GitHub environment if deployments should require approval.
Before the first deployment, create /home/deploy/ackbar-web/shared/api.env and web.env on the
server using deploy/env/api.env.example and
deploy/env/web.env.example. Keep them readable only by deploy
(chmod 600). Values must use shell-compatible KEY=value syntax. Automated backup requires an
absolute local SQLite DATABASE_URL; deployment refuses to migrate a remote libSQL database.
Every deployment stops the app briefly, creates and checks an SQLite snapshot, migrates, switches
the release, and restarts ackbar-api and ackbar-web. Failure restores the prior release and snapshot.
The repository's .nvmrc selects its own Node.js major without changing the server's NVM default,
and its pinned PM2 package runs with isolated state in /home/deploy/ackbar-web/shared/pm2. The first
deployment removes only ackbar-api and ackbar-web from the server-wide PM2 daemon; other PM2
applications and the default Node.js version are not changed.
The Sync production card catalog GitHub Actions workflow downloads and upserts the current SWU API
bulk export every day at 07:17 UTC. It can also be run manually with workflow_dispatch, including
once immediately after the first deployment to populate an empty production catalog. It shares the
deployment concurrency group and uses a server-side lock, so imports cannot overlap deployments or
one another. A failed import leaves the existing catalog intact and reports a failed workflow run.
Roll back code while preserving current data with:
ssh "deploy@$DEPLOY_HOST" 'bash /home/deploy/ackbar-web/current/scripts/rollback.sh'To also undo the last migration, restore its pre-deployment snapshot. This discards database writes made since that deployment:
ssh "deploy@$DEPLOY_HOST" 'bash /home/deploy/ackbar-web/current/scripts/rollback.sh --restore-db'Publications expire seven days after creation. Owners can deactivate them, which removes them from the marketplace and prevents new claims while preserving existing claims and reputation history.