docs: add directory, write getting started guide

README.md

@@ -4,36 +4,8 @@
 A website created with the latest and greatest web technologies.
 May contain blackjack and other things one tends to include in awesome projects.
 
-## Installation
-
-    git clone --recursive https://github.com/Programvareverkstedet/nettsiden.git
-
-Put it in a folder your webserver can find.
-
-## Development setup
-
-The development environment can be setup with:
-
-    nix develop
-
-For this you will need to install the nix package manager and possibly set the experimental features in your nix config, likely located at /etc/nix/nix.conf or $HOME/.config/nix/nix.conf.
-
-Installing nix with your package manager might not work without some tweaking, but the upstream script should just work which you can find [here](https://nixos.org/download/).
-
-    experimental-features = flakes nix-command
-
-You can then run the server with:
-
-    runDev
-
-### Admin account
-
-Login goes through `idp.pvv.ntnu.no` via SAML, so you have to use your PVV account.
-(This only works if you use access the local development site via the the hostname `localhost`)
-To make your account into an admin account, run:
-
-    sqlite3 pvv.sqlite "INSERT INTO users (uname, groups) VALUES ('YOUR_USERNAME', 1);"
+See [Getting Started](./docs/getting-started.md) for help to hack on the project.
 
 ## Hosting
 
-![](./.gitea/hosting.jpg)
+![](./docs/hosting.jpg)

docs/getting-started.md

@@ -0,0 +1,72 @@
+# Getting started
+
+Let's get you up and running.
+
+## List of dependencies
+
+You will need to install the following pieces of software:
+
+- Git
+- SQLite3
+- PHP
+- Composer
+- OpenSSL
+
+If you are running Ubuntu or Debian, you can install these dependencies with:
+
+```bash
+sudo apt update
+sudo apt install git sqlite3 php composer openssl
+```
+
+## Automatic setup
+
+You can use the scripts in the `scripts/` directory to quickly set up a development environment.
+
+By running the `./scripts/setup.sh`, all dependencies will be installed, in addition to other miscellaneous setup tasks. You can then run `./scripts/run.sh` to start the webserver.
+
+You should now be able to access the site at [http://localhost:1080](http://localhost:1080).
+
+Sometimes it is useful to completely reset the state of the project, deleting the data, redownloading dependencies, etc. You can do this by running `./scripts/reset.sh`. Be careful, as this will delete all data in the database!
+
+> [!WARN]
+> Even when resetting the project with the reset script, there are some situation where you need to clear your cookies or your browser cache to get a clean state.
+> How to do this varies between browsers, so please refer to your browser's documentation for instructions.
+
+## Setup with nix
+
+We provide a devshell with all dependencies included. We do recommend still using the scripts for setup tasks.
+
+```bash
+nix develop
+./scripts/setup.sh
+./scripts/run.sh
+```
+
+## Logging in
+
+We have a development configuration for SimpleSAMLphp (which we use as our authentication system), that lets you log in with dummy users while developing.
+
+The available users are:
+
+- `admin` (password: `admin`) - An admin user
+- `user` (password: `user`) - A normal user
+
+In addition, if you need to look into the SAML setup, you can log into the SimpleSAMLphp admin interface at [http://localhost:1080/simplesaml/admin](http://localhost:1080/simplesaml/admin) with username `admin` and password `123`.
+
+## The codebase
+
+In the codebase, you will find the following directories:
+
+- `dist`: Contains files related to deployment, hosting and packaging.
+- `docs`: Documentation for the project.
+- `inc`: PHP include files, containing a base set of useful classes, functions and constants.
+- `nix`: Nix config for packaging, devshells, NixOS modules, etc.
+- `scripts`: Helper scripts for setting up development environments, running the server, etc.
+- `src`: The main library code for the project. This contains raw PHP code with business logic and database access.
+- `vendor`: Third-party dependencies installed with composer.
+- `www`: The webroot for the project. This contains public assets, styling, javascript and PHP code concerned with routing and rendering webpages.
+
+## How SimpleSAMLphp is set up in the development environment
+
+It used to be the case that we would connect to our production instance of SimpleSAMLphp for authentication even in development environments. This is no longer the case, as we now use our local SimpleSAMLphp instance both as a service provider and as an identity provider in development. The `config.php` and `authsources.php` files are written in a way where one single instance of SimpleSAMLphp acts as both parts. It will send authentication requests to itself. See `dist/simplesaml-dev` for implementation details.

nix/shell.nix

@@ -1,4 +1,4 @@
-{ pkgs, lib }:
+{ pkgs }:
 let
   phpEnv = pkgs.php84.buildEnv {
     extensions = { enabled, all }: enabled ++ (with all; [ iconv mbstring pdo_mysql pdo_sqlite ]);
@@ -14,45 +14,4 @@ pkgs.mkShellNoCC {
     sql-formatter
     openssl
   ];
-
-  # Prepare dev environment with sqlite and config files
-  shellHook = ''
-    alias runDev='php -S localhost:1080 -d error_reporting=E_ALL -d display_errors=1 -t www/'
-
-    declare -a PROJECT_ROOT="$("${lib.getExe pkgs.git}" rev-parse --show-toplevel)"
-
-    mkdir -p "$PROJECT_ROOT/www/galleri/bilder/slideshow"
-    test -e "$PROJECT_ROOT/pvv.sqlite" || sqlite3 "$PROJECT_ROOT/pvv.sqlite" < "$PROJECT_ROOT/dist/sql/pvv_sqlite.sql"
-    test -e "$PROJECT_ROOT/config.php" || cp -v "$PROJECT_ROOT/dist/config.local.php" "$PROJECT_ROOT/config.php"
-
-    if [ ! -d "$PROJECT_ROOT/vendor" ] ; then
-      pushd "$PROJECT_ROOT"
-      composer install || exit $?
-
-      # Set up SimpleSAMLphp identity provider (for local testing)
-      install -m644 dist/simplesaml-dev/authsources.php -t vendor/simplesamlphp/simplesamlphp/config/
-      install -m644 dist/simplesaml-dev/config.php -t vendor/simplesamlphp/simplesamlphp/config/
-      install -m644 dist/simplesaml-dev/saml20-idp-remote.php -t vendor/simplesamlphp/simplesamlphp/metadata/
-      install -m644 dist/simplesaml-dev/saml20-idp-hosted.php -t vendor/simplesamlphp/simplesamlphp/metadata/
-      install -m644 dist/simplesaml-dev/saml20-sp-remote.php -t vendor/simplesamlphp/simplesamlphp/metadata/
-
-      # See session.phpsession.savepath in config.php
-      mkdir -p vendor/simplesamlphp/simplesamlphp/sessions/
-
-      openssl req \
-        -newkey rsa:4096 \
-        -new \
-        -x509 \
-        -days 3652 \
-        -nodes \
-        -out vendor/simplesamlphp/simplesamlphp/cert/localhost.crt \
-        -keyout vendor/simplesamlphp/simplesamlphp/cert/localhost.pem \
-        -subj "/C=NO/ST=Trondheim/L=Trondheim/O=Programvareverkstedet/CN=localhost"
-
-      cp dist/config.local.php config.php
-
-      ln -s ../vendor/simplesamlphp/simplesamlphp/public/ www/simplesaml
-      popd
-    fi
-  '';
 }