Add documentation

README.md

@@ -1 +1,83 @@
-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.

backend/README.md

@@ -0,0 +1,12 @@
+# backend
+
+A local mongodb instance is required.
+
+```bash
+cd backend/cmd/exam-poll
+
+# modify .env.dev to your needs
+
+# run the application
+go run .
+```

frontend/README.md

@@ -1,6 +1,8 @@
+# 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 +14,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.