📚 Louise-Schroeder-Gymnasium 📝

Full-Stack Repository for our School  🚌

---

Introduction • Get Started • Recommendations • Help • Documentation • Contributing • Tech Stack • License

🚨 DEPRECATION/ARCHIVAL NOTICE 🚨

Thanks for stopping by, but although possibly useful, this code might be outdated by the time you're reading this and does not reflect the project status. You can find the current implementation here. See you there! 👋

Looking for the old version using Next.js with an Apollo+Nexus GraphQL stack? Find it here: (archive)

Introduction

👋 Hey!
You're looking at the source code behind the new Louise-Schroeder-Gymnasium website right now! 🤯 It houses a full-stack Remix application, loaded with TypeScript, Prisma and a bunch of other goodies. It's not out yet, but we're working on it. Wanna help out? 😇 See how to get started, take a look at the tech stack, or dig straight into the documentation. 👀

Public Money, Public Code

Why is software created using taxpayer money, written for the public sector, existing solely to serve the public, not released in the public? Too often government spends a considerable amount of money on software which is outdated by the time it arrives, not maintained appropriately, contains serious bugs and/or ultimately can't be trusted to respect the security and privacy of the people who paid for it. That's why this project is licensed under the GNU Affero General Public License. We believe that code written for the public sector should be free and open for the public to run, study, copy, change, distribute and improve. If it is public money, it should be public code as well. 💰

Quickstart

Impatient? Spin up a GitPod environment in seconds and you're good to go:

Please provide feedback and take a look at the guide below if things break unexpectedly while following these steps carefully:

1. Click the button above to launch a Visual Studio Code editor in your browser, without having to go through the setup below
2. GitPod will prompt you to sign in with your GitHub account (do that)
3. When the instance has started and VSCode opens in your browser, you will see a bunch of stuff going on in the Terminal (this is normal, don't freak out - your environment is being setup for you automatically using the commands that are detailed in the guide below)
4. There will probably be a couple pop-ups in the bottom right. Look for the one that asks if you want to install the recommended extensions for this project, and select "Install" (or similar). You can close the others.
5. While the extensions are being installed, you will be flooded with a bunch of tabs about them. These tabs can be closed with the "x" next to them in the VSCode tab bar at the top of the editor
6. Once the terminal commands have completed, you will see a green checkmark saying "[SERVER] ✅ http://localhost:3000" in the terminal
7. A preview of the app (at localhost:3000, a special internet address that goes directly to the webapp on GitPod) should open automatically in a "Simple Browser" tab (if it says "Port 3000 not found", hit "Try Again" after a couple seconds, and check if nothing has gone wrong in the terminal)
8. From here, you should be able to browse the code from the file tree in the panel on the left. Try editing a file (such as app/routes/__pages/index.tsx) by adding or removing some text and watch the browser preview reload automatically, reflecting the changes you just made.
9. Familiarize yourself with the tech stack, the developer docs, the Contributing section and the guide below to get the most out of your coding session. If you don't know where to start, read the Helpful Resources recommendations.
10. You may want to reload the GitPod environment before starting to code for the first time using Ctrl + Shift + P -> "Developer: Reload Window". If the keyboard shortcuts don't work, open the command palette manually by clicking the settings cogwheel in the bottom left corner, then selecting "Command Palette..."
11. You're ready to code and build something awesome. Have fun! 😎

When you're done, just close the browser tab/window, and GitPod will terminate your VSCode instance within a few minutes automatically. You can reopen it, and any changes you haven't permanently saved by committing them to this repository yet, within 14 days from the GitPod dashboard. Read on to learn more.

Get Started 💨

Prerequisites: You understand basic terminal commands, how to teach yourself from online resources and how to get around in a programming environment (Check the helpful resources section if you're not sure). You run a supported operating system (GNU+Linux, BSD, macOS, Windows) and have a package manager installed (No? Install Homebrew on macOS or Install winget on Windows. GNU+Linux/BSD-based distributions commonly come with a package manager you should already be familiar with)

Open a terminal (you'll probably want to keep this around):

• (GNU+Linux, BSD) ⊞ Win (App Launcher) -> open Terminal/Konsole
• (macOS) ⌘ + Space -> open Terminal.app
• (Windows) ⊞ Win + R -> cmd (my condolences)

Make sure you have the latest version of Node.js and NPM (the Node package manager, which should ship with it) installed:

• (GNU+Linux, BSD) $ pacman -S nodejs
• (macOS) $ brew install node
• (Windows) $ winget install -e --id OpenJS.NodeJS

(The package manager pacman is specific to the Arch GNU+Linux distribution. Always check your distribution-specific Debian/Fedora/Ubuntu/... documentation first, as commands may differ)

Make sure you have the latest version of git installed, which you will need to use to download our code, share your changes and collaborate with others (GitHub is the server provider that stores our code and interfaces with git):

• (GNU+Linux, BSD) $ pacman -S git
• (macOS) $ brew install git
• (Windows) $ winget install -e --id Git.Git

If you want to contribute code, you'll probably want to configure git to use your name and email, associating your contributions with your GitHub account:
git config --global user.name "<your GitHub username>"
git config --global user.email "<your GitHub email>"

Clone this repository with git (This will "download" the code and keep a special directory around (.git) to track your changes and make collaboration easier):

$ cd ~/Folder/you/want/to/clone/this/repository/into
$ git clone https://github.com/3x071c/lsg-remix.git

Tip: Use Tab to complete terminal commands and show suggestions

Open the project in Visual Studio Code, our recommended IDE (code editor):

$ code lsg-remix

Make sure to trust the folder and install all recommended extensions (If you're new to Visual Studio Code, check out the next section as well). You can close the automatically opened tabs with the installed extensions.

Installation instructions for Visual Studio Code:
(GNU+Linux, BSD) pacman -S code (limited OSS version) / yay -S visual-studio-code-bin (Research required!)
(macOS) brew install --cask visual-studio-code
(Windows) winget install -e --id Microsoft.VisualStudioCode

Install the dependencies of this project (you can open up a Terminal in VSCode with Ctrl + J):

$ npm i

Now, you'll need to setup a PostgreSQL database. There are many ways you can get one up and running (ask the internet); we're going to focus on two "officially recommended" ones here:

---

1. Setup a local PostgreSQL database yourself

• (GNU+Linux, BSD) pacman -S postgresql
• (macOS) brew install --cask postgres-unofficial
• (Windows) winget install -e --id PostgreSQL.PostgreSQL

If you are on macOS, postgres-unofficial installs Postgres.app, which provides a handy UI and sane defaults to get started with little friction (no need for command-line configuration!)

There are lots of tutorials available online on setting up a PostgreSQL database natively. You will need to make a database connection available at a certain port (commonly 5432) of your local machine (localhost).

2. Have docker setup PostgreSQL for you

(You will need docker though)

• (GNU+Linux, BSD) pacman -S docker docker-compose
• (macOS) brew install podman docker-compose; podman machine init; podman machine start; alias docker='podman'
• (Windows) ???

Note: On macOS and Windows, docker (a "containerization" solution) does not run natively, but through some sort of VM that provides a GNU+Linux, BSD environment for docker. A common recommendation here is Docker Desktop by the Docker team (a fine option), though note that it has a very user-restricting license which we can't endorse. Podman is a better alternative if you're ok with reading a little. You can treat the podman command as a drop-in docker replacement, and even alias it (on UNIX-like systems, that is)

Make sure to install both docker (or a docker equivalent) AND docker-compose to proceed:

$ npm run up
...

Docker Compose will orchestrate a PostgreSQL database from the included docker-compose.yml file for you!

Side note: If you're working a lot with the build system, having a working docker installation around is going to save you a lot of time, as Fly deploys docker containers!

Use the connection string postgresql://postgres:postgres@localhost:5432/postgres to connect to the database (see the instructions on populating the .env file below)

---

Create a .env file, containing static key-value pairs for environment-specific configuration. The .env.example file serves as a good starting point. You'll need your PostgreSQL connection string from the previous step here, to tell the app (/prisma) where and how to connect to your database.

To securely generate a random password on your computer:
(GNU+Linux, BSD/macOS) openssl rand -base64 40
(Windows) ??? (use this instead)

The MAGIC_* variables hold the public and private (secret) API keys for Magic, our chosen authentication solution. During local development, Magic runs in Test Mode - this allows you to use "[email protected]" (or [email protected]) to simulate a real-world successful/failed login while bypassing the regular magic link authentication scheme. Consequently, the environment variables may be populated with "dummy" values for development. In production, values from the Magic admin dashboard are provided.

Run our setup script to fill your database with "seeded" sample records and generate code necessary for development:

$ npm run new

Spin up a local development server. It will automatically reflect changes in the code:

$ npm run dev

You likely want to show debug messages using the following command instead: npx cross-env DEBUG='*' npm run dev If you want to view debug messages in the browser too, follow the instructions here by executing the localStorage line in your browser's console (etc.)

Before you start working:

$ git status # Check if everything's fine
$ git checkout trunk # Move to the default branch in case you aren't
$ git pull --all --rebase # Make sure you're up-to-date by "pulling" the latest changes
$ git checkout -b <build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test>/<your idea> # Start off with a feature branch
$ # examples:
$ git checkout -b feat/add-cat-gifs
$ git checkout -b fix/zalgo-bug
$ git checkout -b chore/bump-deps
$ git checkout -b refactor/folder-structure
$ # ...

Commit changes in reasonable chunks regularly while working (make sure everything works before committing):

$ npm run commit # Make sure to always commit using conventional commit messages if you commit with a different tool (see https://www.conventionalcommits.org/ for more info)

Push your changes to GitHub so others can follow your progress (you will need repository access):

$ git push --prune -u origin HEAD # Authenticate with your GitHub credentials (See here for how to save them: https://git-scm.com/book/en/v2/Git-Tools-Credential-Storage)

Open a draft pull request (PR) on GitHub from your branch to the default branch (trunk) and watch the status checks complete. The title of the PR should follow the same format as your commits, the body should include all necessary information for others to understand what the branch changes. Fly (and a bunch of scripts) will build a live preview of your PR! (Each deployment usually takes around 7 minutes)

Once your branch is ready to be published, convert the draft PR into a regular one, and kodiak (a bot) will automatically take care of "squashing" your changes into a single commit onto the default branch. Make sure to familiarize yourself with the Contributing guide, and request reviews from others (using the sidebar) when appropriate, before "un-drafting" your PR.

Happy hacking! 🥳

Recommendations for VSCode

The workspace settings and recommended extensions in this repository are limited to basic support for the technologies used. If you haven't already configured your editor to your liking, here are some more recommendations:

VSCode user preferences (Open via command palette (Ctrl + Shift + P) -> Preferences: Open Settings (JSON))

{
  "editor.bracketPairColorization.enabled": true,
  "editor.cursorBlinking": "smooth",
  "editor.cursorSmoothCaretAnimation": true,
  "editor.fontFamily": "\"<Install a Nerd Font (https://www.nerdfonts.com), insert its full name here>\", \"Fira Code\", monospace",
  "editor.fontLigatures": true,
  "editor.formatOnPaste": true,
  "editor.formatOnSave": true,
  "editor.guides.bracketPairs": "active",
  "editor.inlineSuggest.enabled": true,
  "editor.linkedEditing": true,
  "editor.smoothScrolling": true,
  "editor.suggest.preview": true,
  "editor.suggestSelection": "first",
  "editor.wordWrap": "on",
  "emmet.triggerExpansionOnTab": true,
  "javascript.inlayHints.enumMemberValues.enabled": true,
  "javascript.updateImportsOnFileMove.enabled": "always",
  "prettier.requireConfig": true,
  "prettier.useEditorConfig": true,
  "prettier.withNodeModules": false,
  "stylelint.reportInvalidScopeDisables": true,
  "stylelint.reportNeedlessDisables": true,
  "telemetry.telemetryLevel": "off",
  "terminal.integrated.cursorBlinking": true,
  "terminal.integrated.cursorStyle": "line",
  "typescript.inlayHints.enumMemberValues.enabled": true,
  "typescript.updateImportsOnFileMove.enabled": "always",
  "window.autoDetectColorScheme": true,
  "workbench.iconTheme": "<file icon theme>",
  "workbench.list.smoothScrolling": true,
  "workbench.preferredDarkColorTheme": "<dark color scheme>",
  "workbench.preferredHighContrastColorTheme": "<high contrast color scheme>",
  "workbench.preferredLightColorTheme": "<light color scheme>",
  "workbench.productIconTheme": "<product icon theme>"
}

A few theme recommendations if the default themes (Ctrl + K + T (color scheme), Ctrl + Shift + P -> Preferences: Product Icon Theme/Preferences: File Icon Theme) don't suit you:

• Andromeda Color Scheme
• Fluent Product Icon Theme ✨
• GitHub Color Scheme ✨
• Material Product Icon Theme
• Material Color Scheme
• Material File Icon Theme
• Monokai Pro Color Scheme ✨
• One Dark Pro Color Scheme
• Palenight Color Scheme
• Shades of Purple Color Scheme

Some extension recommendations:

• Better Comments
• GitLens - Git supercharged
• Import Cost
• NPM Version Lens
• Visual Studio IntelliCode

That's it, you're good to go! 🤩

Helpful Resources

Here are some pointers to completely free, yet incredibly valuable learning resources if you've just started dipping your toes into web development in general, or are new to React, TypeScript, etc:

• Brian Will published a playlist of videos teaching fundamental Programming Language principles
• w3schools targets newcomers to web development, approaching web development fundamentals in a simplified way
• FreeCodeCamp hosts long video sessions, going through the entire web and software development process
• The MDN Developer Web Development series provides a great starting point for both beginners and advanced developers (re-)exploring HTML, CSS and JavaScript
• The Re-Introduction to JS by MDN, if you already know "old-school" JavaScript, specifically focuses on more recent changes to the JavaScript landscape that have shaped the language, the ecosystem and this project, refreshing knowledge and bringing you up to speed with the latest developments
• Traversy Media provides long videos showing the development with and integration of JavaScript stacks and projects
• Even though this project uses Remix and NOT Next.js (we used to, sometime ago), the Next.js learning website is a very well illustrated take on React and React framework familiarization. A lot of concepts in Next.js can be transferred to Remix, so don't hesitate learning them.
• The React website itself has a getting started guide and a full tutorial, as well as an overview, about React and advanced JavaScript development
• Fireship does videos on the JavaScript landscape, with entertaining shorts and longer explorations
• If you're familiar with old JavaScript stacks and libraries, such as Knockout, Handlebars or MVC frameworks, then the official Introduction to React.js, or (the more entertaining) Rethinking best practices talk by a React maintainer at Facebook, both from 2013 may be helpful (note that nowadays, React components have improved to mainly use functions instead of classes)
• Ben Awad makes comedic videos on TypeScript, React, related technologies and decision-making in one of the largest programming language ecosystems
• Understanding the event loop (YouTube) isn't necessary, but definitely helpful to understanding modern JavaScript performance and user experience optimization
• Google's web.dev showcases advanced concepts and guides to intermediate developers
• The Visual Studio Code YouTube channel contains informative shorts on tips & tricks to optimize productivity with VSCode
• The Remix YouTube channel and Chakra UI YouTube channel provide an audiovisual alternative to learn more about these dependencies
• Luke Smith has some videos focusing on UNIX principles, educating about the usefulness of command-line utilities on operating systems such as macOS and GNU/GNU+Linux, BSD

Want to contribute a helpful resource for others to learn from? Open an issue!

Documentation

See Docs

Contributing

See Contributing

Tech Stack

• Git - Version Control
• Editorconfig - IDE file style consistency
• Prettier - Code formatting
• ESLint - JavaScript linting
• CSpell - Spell checker
• SecretLint - Prevent secret leakage
• jscpd - Copy/paste detector
• Commitlint - Conventional Commit Validator
• Commitizen - Conventional Commit Prompt
• GitHub Actions - Continuous Integration
• NodeJS - Server-Side JavaScript
• TypeScript - Typed JavaScript superset/compiler
• React - Declarative, component-based, reactive UI library
• Remix - SSR React Framework using React-Router
• Chakra UI - React component framework
• Emotion - CSS-in-JS library used by Chakra UI
• Lodash - Utility functions
• Prisma - Database ORM
• Fly - Continuous Deployment

License

This project is licensed under the GNU Affero General Public License (GNU AGPL 3.0 or later).
It is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. A copy of the GNU Affero General Public License Version 3 should be distributed along with this program here. If not, see the official GNU license website.