This is the community-built, open-source website for Alveus Sanctuary. You can access the site at alveussanctuary.org (or alveus.gg).
This project uses PNPM workspaces. The main app is the website package (apps/website), which is a Next.js app.
For development:
- Node.js
- PNPM with workspaces
- Prettier (code formatting)
- ESLint (code linting)
- Docker (Compose) (local MySQL + S3 [MinIO])
Website stack (based on T3 Stack):
- TypeScript
- Next.js (framework)
- tRPC (typesafe API)
- Prisma (database ORM)
- Auth.js aka NextAuth.js (auth via OAuth)
- Tailwind CSS (styling)
Hosting (production):
- PlanetScale (MySQL database)
- Vercel (serverless hosting)
- DigitalOcean Spaces (S3-compatible storage)
- Upstash QStash (Simple Queue Service)
- Twitch OAuth (application)
- Twitch Helix
For a more complete overview see: #9
Hey there! Welcome to Alveus.gg! There's a few ways that you can help contribute.
- If you find a bug - you can fill out a bug report
- If you have an idea that would make Alveus better - please fill out an idea issue
- If you have development experience, take a look at our issues labeled good first issue, read our contributing guide and agree to our code of conduct before you get started.
Note
If you only want to work on the front end, you may skip the prerequisite and skip setting up a database or file storage (step 5). But you may encounter some errors when running the website without a database or file storage.
If you aren't working on features related to Twitch authentication, you can set the DISABLE_ADMIN_AUTH to true in your apps/website/.env file (see step 6 and 6.i) in order to use the admin dashboard immediately. Otherwise, create a Twitch application, setting the OAuth callback to be http://localhost:3000/api/auth/callback/twitch. Note down your client ID and client secret.
- Install Node.js using a version manager like
nvmorfnm. Runnvm install/fnm installin the project directory to install andnvm use/fnm useto use the correct Node.js version. Alternatively see nodejs.org for other options to download and install Node.js. You can see what version we need inpackage.jsonunderengines. - Use
corepack enableto use pnpm as the package manager. Corepack is a tool provided with Node.js that makes it easy for you to use the specific package manager we expect. - Authenticate with the GitHub Package Registry:
npm login --auth-type=legacy --registry=https://npm.pkg.github.com- Use your GitHub username (lowercase) as the username when prompted
- Create a GitHub personal access token (classic) with the
read:packagesscope and use it as the password when prompted
- Install dependencies:
pnpm install --frozen-lockfile - Run
docker compose up -dfrom withinapps/websiteto start a local MySQL database, and an S3 bucket with MinIO. - Copy
apps/website/.env.exampletoapps/website/.envand open your copy in a text editor and fill it:- If your feature is not related to Twitch authentication, you can set
DISABLE_ADMIN_AUTHtotruein order to use the admin dashboard without authentication. Otherwise, fill inTWITCH_CLIENT_IDandTWITCH_CLIENT_SECRETas mentioned above. - The vapid keys for web notifications have to be generated using
pnpx web-push generate-vapid-keys - The Next Auth secret (
NEXTAUTH_SECRET), Action API secret (ACTION_API_SECRET) and Vercel Cron Secret (CRON_SECRET) have to be filled with 32-byte Base64-encoded secrets. See Generate secrets below. - The data encryption passphrase (
DATA_ENCRYPTION_PASSPHRASE) has to be filled with a 24-byte Base64-encoded secret. See Generate secrets below. - You may define a Weather API key (
WEATHER_API_KEY) to use the weather API and stream overlay. See Weather API below. - If you are using Twitch authentication, you may define privileged users once they have signed in in the
SUPER_USER_IDSvariable with their CUID (using comma separated values)
- If your feature is not related to Twitch authentication, you can set
- Copy
apps/database/.env.exampletoapps/database/.env - Push the database schema to the new database using
pnpm prisma db pushfrom withinapps/database. - Start the dev server using
pnpm devfrom withinapps/website - The website should be running at
http://localhost:3000/(open in browser)
- Learn more about the stack at Create T3 App - Introduction
- You can use the Prisma Studio to view your database. Launch it with
pnpm prisma studiofrom withinapps/database - You can access a direct MySQL CLI to the database with
docker compose exec db sh -c 'MYSQL_PWD=$MYSQL_ROOT_PASSWORD mysql alveusgg' - If you're using VSCode, add
"typescript.tsdk": "node_modules/typescript/lib"+"eslint.workingDirectories": [{ "pattern": "apps/*" }]to.vscode/settings.jsonto ensure you're using the correct TypeScript version + ESLint working directories
We use Base64-encoded random strings for various secrets. To generate these secrets you can use OpenSSL or Python. OpenSSL should be preinstalled on most Unix-like systems (Linux, macOS, WSL). If neither is installed on your system, you may need to install it yourself.
- Using OpenSSL:
- Generate a 32-byte secret:
openssl rand -base64 32 - Generate a 24-byte secret:
openssl rand -base64 24
- Generate a 32-byte secret:
- Using Python:
You may need to call
python3instead depending on your installation.- Generate a 32-byte secret:
python -c "import os, base64; print(base64.b64encode(os.urandom(32)).decode('utf-8'))" - Generate a 24-byte secret:
python -c "import os, base64; print(base64.b64encode(os.urandom(24)).decode('utf-8'))"
- Generate a 32-byte secret:
Alveus operates a weather station on-site that uploads data to wunderground.com. Wunderground provide an API via api.weather.com that we use to display the weather for the stream overlay (and in the API for the Twitch chat bot). Accessing the API required an API key, which is only granted to users that have a weather station on wunderground.com.
It seems that anyone can sign up for a Wunderground account and register a weather station on the site, at which point you'll be granted access to the API, without ever needing to actually connect a weather station and upload data. It seems you can use this to get an API key to develop with the weather API locally.
In production, we use the actual API key for the account that is associated with the Alveus weather station, which does upload data to the site.
We use Cloudflare Stream to host a low-latency variation of the live cams specifically for camera operators. To do that, we need to do some setup with Cloudflare.
-
Login to the Cloudflare dashboard and navigate to Stream -> Live Inputs and click "Create Live Input"
-
Tick the "Require Signed URLs" box and leave the rest of the defaults
-
Click "Create Live Input" button
-
Make a note of the "Live Input ID", this will be used to configure the
CF_STREAM_LOLA_VIDEO_IDenvironment variable. -
Make a note of the host, this will be used to configure the
CF_STREAM_HOSTenvironment variable. It will look likecustomer-<unique-customer-id>.cloudflarestream.comand can be found under Connection Info -> WebRTC (WHIP) -> WebRTC (WHIP) URL. -
Create an API token with the
Stream:Editpermission. This is sometimes referred to as "Stream" under the "Account" dropdown. -
Use that token to make a request to create a set of signing keys for Cloudflare Stream. This is global to the account, not just this specific stream.
-
Make a note of the
idandjwkvalues, these will be used to configure theCF_STREAM_KEY_IDandCF_STREAM_KEY_JWKenvironment variables. -
Ensure that the following environment variables are set in
apps/website/.env:CF_STREAM_KEY_IDCF_STREAM_KEY_JWKCF_STREAM_LOLA_VIDEO_IDCF_STREAM_HOST
The stack should work on any Node.js server or Next.js capable hosting provider and any MySQL server, but has only been tested on Vercel (and PlanetScale) for now.
- Create a twitch application (see Development setup above)
- Create a PlanetScale account or provide your own MySQL server, that should give you two DSN for the main and shadow database (something like
mysql://user:pass@us-east.connect.psdb.cloud/alveusgg?sslaccept=strictandmysql://user:pass@us-east.connect.psdb.cloud/alveusgg/shadow?sslaccept=strict) - Set up some S3-compatible storage for file uploads (e.g. DigitalOcean Spaces, Backblaze R2 or AWS S3)
- Go through the
apps/website/.env.exampleand create your ownapps/website/.env.production(see Development setup above) and also:- Fill the Prisma section with the database info (DSN)
- Fill in the S3 section with your S3-compatible storage info
- Push the database schema to the new database using
pnpm prisma db push. - Get your own domain (optional)
- Create a Vercel account
- Create a new Vercel project with these settings:
- General:
- Framework Preset:
Next.js, leave the other build/dev settings on the default option - Root directory:
apps/website - Node.js Version: See
enginesinpackage.jsonfor the required version
- Framework Preset:
- Domains: add your domains
- Git: connect your Git repo
- Environment Variables: Copy your
apps/website/.env.productionhere
- General: