147 lines
4.6 KiB
Markdown
147 lines
4.6 KiB
Markdown
# SHD.build
|
||
|
||
A SvelteKit community application for _The Division Resurgence_. SHD.build
|
||
combines a public game database, loadout builder, shared builds, guides, account
|
||
management, and the ISAC data-management console.
|
||
|
||
See `docs/architecture.md` for the implementation model.
|
||
|
||
## Database
|
||
|
||
The server uses the in-process `@tursodatabase/database` package and a local
|
||
SQLite-compatible file. Turso Cloud is not required.
|
||
|
||
Create or update the local database:
|
||
|
||
```sh
|
||
npm run db:migrate
|
||
```
|
||
|
||
The default file is `data/shd-build.db`. Copy `.env.example` to `.env` and set a
|
||
different location if needed.
|
||
|
||
Store custom avatars 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
|
||
```
|
||
|
||
The seed creates administrator `Aewyn` and standard user `Quartermaster`. It
|
||
generates and displays strong temporary passwords once, then stores only salted
|
||
Argon2id hashes.
|
||
|
||
## Develop
|
||
|
||
```sh
|
||
npm run dev
|
||
```
|
||
|
||
## Encrypted environment files
|
||
|
||
Keep development, staging, and production settings in the committed, encrypted
|
||
`.env.development`, `.env.staging`, and `.env.production` files. Keep private
|
||
decryption keys only in the ignored `.env.keys` file and 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` and replaces staged plaintext
|
||
environment files with encrypted versions. Git has no pre-add hook. Use
|
||
`npm run env:stage` instead of directly adding these two files.
|
||
|
||
Keep `.env.keys` out of Git and retain a backup. Production deployments receive
|
||
`DOTENV_PRIVATE_KEY_PRODUCTION` through their secret manager; do not copy the
|
||
keys file to the server.
|
||
|
||
## Containers and staging deployment
|
||
|
||
The application uses the official SvelteKit Node adapter and a multi-stage
|
||
`Dockerfile`. Keep database files, database backups, user avatars, and uploaded
|
||
game-data icons under `/app/data` on a persistent volume. Inject runtime secrets
|
||
when the container starts; keep them out of the image.
|
||
|
||
[docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) documents the staging Compose topology
|
||
and Gitea Actions deployment. A push to `main` validates the application, builds
|
||
the candidate image while staging stays online, stops the application and
|
||
scheduler for the database backup and migration, then starts the release.
|
||
|
||
## Passwordless authentication
|
||
|
||
Use passkeys as the preferred sign-in method. Set `APP_ORIGIN` to the exact
|
||
public origin for registration and authentication. Set `PASSKEY_RP_ID` to that
|
||
hostname or a registrable parent domain. Hosted environments use `shd.build`,
|
||
which permits credentials on `shd.build` and `dev.shd.build`. Use `localhost`
|
||
for direct local development.
|
||
|
||
Magic links require `SMTP_HOST`, `SMTP_PORT`, `SMTP_SECURE`, `SMTP_USER`,
|
||
`SMTP_PASSWORD`, and `SMTP_FROM`. Use `SMTP_SECURE=true` on port 465. Use
|
||
`false` on port 587 and upgrade with STARTTLS. An account owner activates an
|
||
email identity by following a 15-minute, single-use verification link.
|
||
|
||
## Validate
|
||
|
||
```sh
|
||
npm run check
|
||
npm run build
|
||
```
|
||
|
||
[`sv`](https://github.com/sveltejs/cli) creates and configures Svelte projects.
|
||
|
||
## Creating a project
|
||
|
||
```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
|
||
|
||
Install dependencies with `npm install` (or `pnpm install` or `yarn`), then
|
||
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
|
||
|
||
Build a production version:
|
||
|
||
```sh
|
||
npm run build
|
||
```
|
||
|
||
Preview the production build with `npm run preview`.
|
||
|
||
> Deployments may require an [adapter](https://svelte.dev/docs/kit/adapters) for
|
||
> the 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).
|