149 lines
5.0 KiB
Markdown
149 lines
5.0 KiB
Markdown
# SHD.build
|
||
|
||
A SvelteKit application for creating and sharing loadouts for *The Division Resurgence*.
|
||
|
||
The first increment includes a responsive discovery page, an anonymous builder draft saved to local storage, authentication UI boundaries, an admin data-management preview, and an embedded Turso database foundation. See `docs/architecture.md` for the staged implementation plan.
|
||
|
||
## Database
|
||
|
||
The server uses the in-process `@tursodatabase/database` package with a local
|
||
SQLite-compatible file—there is no Turso Cloud dependency.
|
||
|
||
Create or update the local database:
|
||
|
||
```sh
|
||
npm run db:migrate
|
||
```
|
||
|
||
The default file is `data/shd-build.db`. Copy `.env.example` to `.env` to
|
||
override its location.
|
||
|
||
Custom avatars are stored as metadata-free 256 × 256 WebP files. Set
|
||
`TDR_AVATAR_STORAGE_PATH` to a persistent, writable directory in production;
|
||
it defaults to `data/avatars`. The same configuration works on Windows and
|
||
Linux.
|
||
|
||
Seed the initial local accounts once:
|
||
|
||
```sh
|
||
npm run db:seed-users
|
||
```
|
||
|
||
This creates administrator `Aewyn` and standard user `Quartermaster`. Strong
|
||
temporary passwords are generated and displayed once; only salted Argon2id
|
||
hashes are stored.
|
||
|
||
## Develop
|
||
|
||
```sh
|
||
npm run dev
|
||
```
|
||
|
||
## Encrypted environment files
|
||
|
||
Development, staging, and production settings live in the committed, encrypted
|
||
`.env.development`, `.env.staging`, and `.env.production` files. Private
|
||
decryption keys live only in the ignored `.env.keys` file; back it up in a
|
||
password manager.
|
||
|
||
```sh
|
||
npm run env:decrypt # decrypt all environment files for editing
|
||
npm run env:encrypt # encrypt all environment files again
|
||
npm run env:stage # encrypt and git-add all environment files
|
||
npm run env:decrypt:development # operate on one environment
|
||
npm run env:decrypt:staging
|
||
npm run env:decrypt:production
|
||
npm run env:sync:staging-credentials # copy shared Discord/SMTP values from development
|
||
```
|
||
|
||
The repository pre-commit hook runs `env:stage`, so a commit always replaces
|
||
staged plaintext environment files with encrypted versions. Git does not expose
|
||
a pre-add hook, so use `npm run env:stage` instead of directly adding these two
|
||
files when possible.
|
||
|
||
Never commit or lose `.env.keys`. Production should receive
|
||
`DOTENV_PRIVATE_KEY_PRODUCTION` through its secret manager rather than copying
|
||
the keys file onto the server.
|
||
|
||
## Containers and staging deployment
|
||
|
||
The application uses the official SvelteKit Node adapter and includes a
|
||
multi-stage `Dockerfile`. Database files, database backups, user avatars, and
|
||
uploaded game-data icons live under `/app/data`, which must be a persistent
|
||
volume. Runtime secrets are injected when the container starts and are never
|
||
baked into the image.
|
||
|
||
The staging compose topology and Gitea Actions deployment are documented in
|
||
[docs/DEPLOYMENT.md](docs/DEPLOYMENT.md). Pushes to `main` validate the
|
||
application, build the candidate image while staging remains online, stop the
|
||
application and scheduler briefly, back up the embedded database, migrate it,
|
||
and start the new release.
|
||
|
||
## Passwordless authentication
|
||
|
||
Passkeys are the preferred sign-in method. `APP_ORIGIN` must exactly match the
|
||
public origin used for registration and authentication, while `PASSKEY_RP_ID`
|
||
must be that hostname or a registrable parent domain. The hosted environments
|
||
use `shd.build`, allowing credentials on both `shd.build` and
|
||
`dev.shd.build`. Direct localhost development should use `localhost`.
|
||
|
||
Magic links require `SMTP_HOST`, `SMTP_PORT`, `SMTP_SECURE`, `SMTP_USER`,
|
||
`SMTP_PASSWORD`, and `SMTP_FROM`. Port 465 normally uses
|
||
`SMTP_SECURE=true`; port 587 normally uses `false` and upgrades with STARTTLS.
|
||
Email identities become usable only after the account owner follows a
|
||
15-minute, single-use verification link.
|
||
|
||
## Validate
|
||
|
||
```sh
|
||
npm run check
|
||
npm run build
|
||
```
|
||
|
||
Everything you need to build a Svelte project, powered by [`sv`](https://github.com/sveltejs/cli).
|
||
|
||
## Creating a project
|
||
|
||
If you're seeing this, you've probably already done this step. Congrats!
|
||
|
||
```sh
|
||
# create a new project
|
||
npx sv create my-app
|
||
```
|
||
|
||
To recreate this project with the same configuration:
|
||
|
||
```sh
|
||
# recreate this project
|
||
npx sv@0.16.5 create --template minimal --types ts --install npm .
|
||
```
|
||
|
||
## Developing
|
||
|
||
Once you've created a project and installed dependencies with `npm install` (or `pnpm install` or `yarn`), start a development server:
|
||
|
||
```sh
|
||
npm run dev
|
||
|
||
# or start the server and open the app in a new browser tab
|
||
npm run dev -- --open
|
||
```
|
||
|
||
## Building
|
||
|
||
To create a production version of your app:
|
||
|
||
```sh
|
||
npm run build
|
||
```
|
||
|
||
You can preview the production build with `npm run preview`.
|
||
|
||
> To deploy your app, you may need to install an [adapter](https://svelte.dev/docs/kit/adapters) for your target environment.
|
||
The shared visual language and dashboard conventions are documented in
|
||
[docs/DESIGN_SYSTEM.md](docs/DESIGN_SYSTEM.md).
|
||
|
||
Empirically derived weapon and gear level-range calculations, rounding rules,
|
||
validation boundaries, and regression observations are documented in
|
||
[docs/STAT_LEVEL_SCALING.md](docs/STAT_LEVEL_SCALING.md).
|