tomheaton / alveusgg

alveussanctuary.org / alveus.gg - community-built, open-source website for Alveus Sanctuary, built with Next.js and Tailwind.

Alveus Sanctuary website

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

See also

• Data repository
• Twitch extension

Tech stack

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)

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)

External APIs

• Twitch OAuth (application)
• Twitch EventSub/Helix

Systems overview

For a more complete overview see: #9

How to contribute

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.

How to develop / Getting started

Note

If you only want to work on the front end, you may skip the prerequisites and skip configuring a database or file storage (steps 3, 4.i, 4.ii and 5). But you may encounter some errors when running the website without a database or file storage.

Prerequisites

1. 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.
2. Set up some S3-compatible storage for file uploads:
   • locally (e.g. Minio or Localstack)
   • online (e.g. DigitalOcean Spaces, Backblaze R2 or AWS S3)

Local development

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. Create a PlanetScale account (free) or provide your own MySQL server, that should give you two DSN for the main and shadow database (something like mysql://user:[e-mail]/alveusgg?sslaccept=strict and mysql://user:[e-mail]/alveusgg/shadow?sslaccept=strict)
4. Copy apps/website/.env.example to apps/website/.env
   1. Fill the Prisma section with the database info (DSN)
   2. Fill in the S3 section with your S3-compatible storage info
   3. The vapid keys for web notifications have to be generated using npx web-push generate-vapid-keys
   4. Next Auth secret (NEXTAUTH_SECRET), Twitch EventSub API secret (TWITCH_EVENTSUB_SECRET) and Action API secret (ACTION_API_SECRET) have to generated using openssl rand -base64 32
   5. The DATA_ENCRYPTION_PASSPHRASE has to generated using openssl rand -base64 24
   6. You may define privileged users once they have signed in via the SUPER_USER_IDS variable (using comma separated values)
5. Push the database schema to the new database using npx 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)

• Also see T3 Stack
• Use npx prisma studio to view your database

How to set up your own production instance

Website

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 extension (see Getting started above)
2. Set up a database (see Getting started above)
3. Go through the apps/website/.env.example and create your own apps/website/.env.production (see Getting started above)
4. Push the database schema to the new database using npx prisma db push.
5. Get your own domain (optional)
6. Create a Vercel account
7. 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 and paste your apps/website/.env.production into the first key field (yes you can simply copy-paste everything at once)