This is the community-built, open-source website for Alveus Sanctuary. You can access the site at alveussanctuary.org (or alveus.gg).

• Data repository
• Twitch extension

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.

1. If you find a bug - you can fill out a bug report
2. If you have an idea that would make Alveus better - please fill out an idea issue
3. 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.

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.

1. Install Node.js (see engines in package.json for the required versions), or use fnm/nvm to install the correct version of Node.js, and use corepack enable to use PNPM.
2. Install dependencies: pnpm install --frozen-lockfile
3. Run docker compose up -d from within apps/website to start a local MySQL database, and an S3 bucket with MinIO.
4. Copy apps/website/.env.example to apps/website/.env and open your copy in a text editor and fill it:
   1. The vapid keys for web notifications have to be generated using pnpx web-push generate-vapid-keys
   2. 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.
   3. The data encryption passphrase (DATA_ENCRYPTION_PASSPHRASE) has to be filled with a 24-byte Base64-encoded secret. See Generate secrets below.
   4. You may define a Weather API key (WEATHER_API_KEY) to use the weather API and stream overlay. See Weather API below.
   5. You may define privileged users once they have signed in in the SUPER_USER_IDS variable with their CUID (using comma separated values)
5. Push the database schema to the new database using pnpm prisma db push from within apps/website.
6. Start the dev server using pnpm dev from within apps/website
7. 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 studio

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
• Using Python: You may need to call python3 instead 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'))"

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.

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.

1. Create a twitch application (see Development setup above)
2. 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:[email protected]/alveusgg?sslaccept=strict and mysql://user:[email protected]/alveusgg/shadow?sslaccept=strict)
3. Set up some S3-compatible storage for file uploads (e.g. DigitalOcean Spaces, Backblaze R2 or AWS S3)
4. Go through the apps/website/.env.example and create your own apps/website/.env.production (see Development setup above) and also:
   1. Fill the Prisma section with the database info (DSN)
   2. Fill in the S3 section with your S3-compatible storage info
5. Push the database schema to the new database using pnpm prisma db push.
6. Get your own domain (optional)
7. Create a Vercel account
8. 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 engines in package.json for the required version
   • Domains: add your domains
   • Git: connect your Git repo
   • Environment Variables: Copy your apps/website/.env.production here