From 37d47325ca4f456a9b290a061ceed16f514091ce Mon Sep 17 00:00:00 2001
From: Fugi <me@fugi.dev>
Date: Tue, 26 Mar 2024 18:28:23 +0100
Subject: [PATCH] Add documentation

---
 README.md          | 78 +++++++++++++++++++++++++++++++++++++++++++++-
 backend/README.md  | 10 ++++++
 frontend/README.md | 17 ++--------
 3 files changed, 89 insertions(+), 16 deletions(-)
 create mode 100644 backend/README.md

diff --git a/README.md b/README.md
index 6bc713f..12ac0e7 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,77 @@
-WIP tool for creating polls about exam marks
+# Exam Poll
+Exam Poll is a tool for creating polls about exam results. It aims to be simplistic and accessible. Anyone can create a poll and share a link to it. Polls can be edited by their creator and run for a specified time span.
+
+The current implementation consists of a backend written in Go, which uses MongoDB, and a server-side rendered frontend using NextJS.
+
+Feel free to use the public instance at [poll.fugi.dev](https://poll.fugi.dev).
+
+## Development
+See the README file in the frontend and backend directories, respectively.
+
+## Deployment
+### Docker Compose
+The compose files I use are provided for reference. You can use them with slight adjustments.
+
+Replace the domains for frontend and api in `docker-compose.prod.yml` and hook up your reverse proxy (which can access the containers via the `swag-net` network, in my case).
+
+Then run the following command to deploy everything:
+```sh
+docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
+ --build
+```
+
+### NixOS module
+This repository includes a Flake that provides a NixOS module for exam poll. You can use it like this:
+
+```nix
+# flake.nix
+{
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+    exam-poll.url = "github:fugidev/exam-poll";
+  };
+
+  outputs = { self, nixpkgs, exam-poll }: {
+    # change `yourhostname` to your actual hostname
+    nixosConfigurations.yourhostname = nixpkgs.lib.nixosSystem {
+      # customize to your system
+      system = "x86_64-linux";
+      modules = [
+        exam-poll.nixosModules.default
+        ./configuration.nix
+      ];
+    };
+  };
+}
+```
+
+```nix
+# configuration.nix
+{
+  services.exam-poll = {
+    enable = true;
+    frontend = {
+      # optionally specify the local port
+      # port = 3000;
+      hostName = "poll.example.com";
+    };
+    backend = {
+      # optionally specify the local port
+      # port = 8000;
+      hostName = "poll-api.example.com";
+    };
+    mongodb = {
+      # provide your own mongodb instance, this is currently not handled by the module
+      uri = "mongodb://localhost:27017";
+      database = "exam-poll";
+      collection = "polls";
+    };
+  };
+}
+```
+
+Nginx will (by default) be automatically configured as reverse proxy with https. This can be disabled by setting `services.exam-poll.configureNginx = false;`.
+
+The creation of a MongoDB instance is currently not handled by the module. Because of MongoDB's non-free license, your options are to use its NixOS module and compile it yourself (requires *a lot* of resources) or to run it in Docker or Podman.
+
+See [`module.nix`](module.nix) for all available options and their explanations.
diff --git a/backend/README.md b/backend/README.md
new file mode 100644
index 0000000..f3560d6
--- /dev/null
+++ b/backend/README.md
@@ -0,0 +1,10 @@
+# backend
+A local mongodb instance is required.
+```bash
+cd backend/cmd/exam-poll
+
+# modify .env.dev to your needs
+
+# run the application
+go run .
+```
diff --git a/frontend/README.md b/frontend/README.md
index 7e33cba..6ed2647 100644
--- a/frontend/README.md
+++ b/frontend/README.md
@@ -1,6 +1,7 @@
+# frontend
 This is a [Next.js](https://nextjs.org/) project bootstrapped with [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app).
 
-## Getting Started
+## Development
 
 ```bash
 # install dependencies
@@ -12,23 +13,9 @@ yarn dev
 
 Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
 
-You can start editing the page by modifying `pages/index.tsx`. The page auto-updates as you edit the file.
-
-[API routes](https://nextjs.org/docs/api-routes/introduction) can be accessed on [http://localhost:3000/api/hello](http://localhost:3000/api/hello). This endpoint can be edited in `pages/api/hello.ts`.
-
-The `pages/api` directory is mapped to `/api/*`. Files in this directory are treated as [API routes](https://nextjs.org/docs/api-routes/introduction) instead of React pages.
-
 ## Learn More
 
 To learn more about Next.js, take a look at the following resources:
 
 - [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
 - [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
-
-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js/) - your feedback and contributions are welcome!
-
-## Deploy on Vercel
-
-The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
-
-Check out our [Next.js deployment documentation](https://nextjs.org/docs/deployment) for more details.