Updated docs (#88)

hugsy · web-flow · commit ec9a89888c2f · 2023-07-04T08:31:01.000-07:00
* updated readme

* added build page

* added missing link for making discord webhooks

* detailed  instructions for rev proxy

* env example file renaming

* updated build instruction for excalidraw

* moved all the rest of the docs into `root/docs`
diff --git a/README.md b/README.md
@@ -23,51 +23,36 @@ _Note_: If you're looking for a platform for hosting CTFs use [CTFd](https://git
 
 A non-exhaustive list of features:
 
- - Full Django + Python 3.10 code
- - Clean (Bootstrap 5+) interface
+ - Django 4 running on Python 3.10, with a clean Bootstrap 5 interface
  - Key-in-hands setup via [`docker-compose`](https://docs.docker.com/compose)
  - Fully integrated around [HedgeDoc](https://github.com/hedgedoc/hedgedoc): smart markdown note mechanism, with [tons of features](https://demo.hedgedoc.org/features)
- - Possibility to create and play private CTFs
- - Create "guests" to your CTFs
+ - Possibility to create and play private CTFs for one player only, making it easy to track your progress on learning platforms like [Root-Me](https://www.root-me.org/), [PicoCTF](https://picoctf.com/), [PentesterLab](https://pentesterlab.com/) and others.
+ - Add "guests" to specific CTFs, allowing non team members to have a limited view of the context
  - View CTF stats, and track members' involment through a cool podium ranking
- - [Jitsi](https://meet.jit.si) integration: instantly jump on video chat with your team mate
- - CTFTime integration: import CTF (+ data) from CTFTime in 2 clicks
+ - CTFTime API integration:  CTF information from CTFTime in one click
  - CTFd/rCTF challenge(s) can optionally be pre-populated locally
  - Basic search engine
- - One step "challenge-notes" → "blog post" export feature
+ - Easily export your challenge notes to create a blog post on Github Pages
+ - [Jitsi](https://meet.jit.si) integration: instantly jump on video chat with your team mate
  - Public & Self-hosted [Excalidraw](https://github.com/excalidraw/excalidraw) integration: draw & share ideas with your team mates
- - Discord notifications
- - ...and more to come...
- - and of course, a Dark mode
+ - [Discord](https://discord.gg) notifications on events (CTF registration, challenge scoring, etc.)
+  - and of course, a Dark mode to save your eyes during those painful sleepless nights
 
 
 ## Build
 
-
 For most people, this will suffice:
 
 ```bash
-$ git clone https://github.com/hugsy/ctfhub
-$ cd ctfhub
+$ git clone https://github.com/hugsy/ctfhub && cd ctfhub
 $ cp .env.example .env
 ### CHANGE THE CREDENTIALS IN .env ###
 $ nano .env
 ### BUILD EXCALIDRAW USING .env VARIABLES ###
-$ make build
 $ docker compose up -d --build
 ```
 
-If you want to use SSL locally, follow the [instructions to generate local SSL certificates](./conf/certs/README.md)
-and run:
-
-```bash
-$ cp scripts/proxy/.env.nginx-proxy.example scripts/proxy/.env
-$ nano scripts/proxy/.env
-### Edit the file to your need
-$ docker compose -f scripts/proxy/docker-compose.yml -f ./docker-compose.yml up -d --build
-```
-
-If you're migrating from the first versions called `ctpad`, check out see [PR #83](https://github.com/hugsy/ctfhub/pull/83) to migrate the data to the new environment, search the `Setup > Migration` part.
+For more advanced building cases, refer to the [Build page](docs/build.md) in the documentation.
 
 
 ## Gallery
diff --git a/docs/build.md b/docs/build.md
@@ -0,0 +1,67 @@
+# Build an instance
+
+## Basic setup
+
+```bash
+$ git clone https://github.com/hugsy/ctfhub
+$ cd ctfhub
+$ cp .env.example .env
+### CHANGE THE CREDENTIALS IN .env ###
+$ nano .env
+### BUILD EXCALIDRAW USING .env VARIABLES ###
+$ docker compose up -d --build
+```
+
+## SSL + nginx reverse-proxy on Docker
+
+A standard secure way to deploy an instance of CTFHub is to use it over an SSL layer, and behind a reverse proxy.
+Using [Let's Encrypt](https://letsencrypt.org/) you can easily generate a valid SSL certificate, which can be used with an nginx container acting as a reverse-proxy. A boilerplate template was provided to you in `scripts/nginx`, which you can use in combination of the [instructions to generate local SSL certificates](./ssl-setup.md). Then run `docker compose` with multiple files as such:
+
+```bash
+$ cp scripts/proxy/.env.nginx-proxy.example scripts/proxy/.env
+$ nano scripts/proxy/.env
+### Edit the file to your need
+$ docker compose -f ./docker-compose.yml -f scripts/proxy/docker-compose.yml up -d --build
+```
+
+Note that the example env file have default variables that may not suit your environment. Adjust them to your needs.
+
+## Deploy your instance for Excalidraw
+
+In `scripts/excalidraw` :
+
+```bash
+$ cd scripts/excalidraw
+$ cp .env.example .env
+$ nano .env
+### edit .env to match your configuration
+$ cd ../..
+$ nano .env
+### update the CTFHUB_EXCALIDRAW_URL setting to point to your local excalidraw
+$ docker compose -f ./docker-compose.yml -f scripts/excalidraw/docker-compose.yml up -d --build
+```
+
+Note that the example env file have default variables that may not suit your environment. Adjust them to your needs.
+
+## Receive Discord notifications
+
+Create a [HTTP Webhook](https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks) on your Discord and paste that link to the setting `CTFHUB_DISCORD_WEBHOOK_URL` in your `.env` file.
+
+## Receive Email notifications
+
+Edit your `.env` and populate the following fields:
+
+```conf
+CTFHUB_EMAIL_SERVER_HOST=''                                 # smtp.gmail.com or mailgun, or sendgrid etc.
+CTFHUB_EMAIL_SERVER_PORT=0
+CTFHUB_EMAIL_USERNAME=''
+CTFHUB_EMAIL_PASSWORD=''
+```
+
+With the appropriate values
+
+
+## Migration
+
+If you're migrating from the first versions called `ctpad`, check out see [PR #83](https://github.com/hugsy/ctfhub/pull/83) to migrate the data to the new environment, search the `Setup > Migration` part.
+
diff --git a/docs/gallery.md b/docs/gallery.md
@@ -1,24 +1,25 @@
-# Gallery
-
-## Dashboard
-
-![dashboard](https://i.imgur.com/vWvgjQ1.png)
-
-## View CTF
-
-![ctf](https://i.imgur.com/kEJo9Jj.png)
-![ctf2](https://i.imgur.com/fe3vvfC.png)
-
-## Import CTFs from CTFtime
-
-![ctftime](https://i.imgur.com/TnOupMe.png)
-
-
-## Challenge
-
-![challenge1](https://i.imgur.com/YRvXs3u.png)
-
-
-## Statistics
-
-![stats](https://i.imgur.com/PGsPztU.png)
+# Gallery
+
+## Dashboard
+
+![dashboard](https://i.imgur.com/vWvgjQ1.png)
+
+## View CTF
+
+![ctf](https://i.imgur.com/kEJo9Jj.png)
+![ctf2](https://i.imgur.com/fe3vvfC.png)
+
+## Import CTFs from CTFtime
+
+![ctftime](https://i.imgur.com/TnOupMe.png)
+
+
+## Challenge
+
+![challenge1](https://i.imgur.com/YRvXs3u.png)
+
+
+## Statistics
+
+![stats](https://i.imgur.com/PGsPztU.png)
+
diff --git a/docs/ssl-setup.md b/docs/ssl-setup.md
@@ -1,21 +1,13 @@
-Place your TLS certificate + private key(s) for your domain here like
-
-```
-./<domain>/fullchain.pem
-./<domain>/privkey.pem
-```
-
-Then edit `../nginx/nginx.conf` to update the path to the chain/key.
+# Using SSL Certificates for a reverse-proxy
 
-Note:
------
+## Development usage
 
 For local development, you can use [mkcert](https://github.com/FiloSottile/mkcert) to generate the certificates.
 
 Example with default settings working with the provided `nginx.conf`:
 
 
-```
+```bash
 # If this is the first time you are using mkcert, create a local CA:
 mkcert -install
 
@@ -29,3 +21,32 @@ mv ctfhub.mydomain.com*.pem ./conf/certs/ctfdad.mydomain.com/fullchain.pem
 ```
 
 If `ctfhub.mydomain.com` is in the `/etc/hosts` file of your machine, then go to `https://ctfhub.mydomain.com` and enjoy the app!
+
+
+## Production usage
+
+### Using Let's Encrypt
+
+Generate your LetsEncrypt keys and certificates
+
+```bash
+sudo apt-get update && sudo apt-get install certbot # if not already installed
+sudo certbot certonly --manual --preferred-challenges=dns
+```
+
+Follow the prompt. Certificates will be generated in `/etc/letsencrypt/live/<domain>` in the containers, which can be found in `./certs` on your host.
+
+Use that path to update the nginx configuration file (in `../nginx/nginx.conf`) and run `docker compose up` including the docker-compose file from this folder.
+
+### Using your own certificates
+
+Place your TLS certificate + private key(s) for your domain here like
+
+```
+./<domain>/fullchain.pem
+./<domain>/privkey.pem
+```
+
+Then edit `../nginx/nginx.conf` to update the path to the chain/key.
+
+
diff --git a/scripts/excalidraw/.env.example b/scripts/excalidraw/.env.example
@@ -0,0 +1,13 @@
+#
+# Redis (required for Excalidraw)
+#
+REDIS_PASSWORD=123234345123123   # Change here
+REACT_APP_BACKEND_V2_GET_URL=http://localhost:3001/api/v2/scenes/ # to Excalidraw
+REACT_APP_BACKEND_V2_POST_URL=http://localhost:3003/api/v2/scenes/ # to Excalidraw-Storage-Backend
+REACT_APP_LIBRARY_URL=https://libraries.excalidraw.com
+REACT_APP_LIBRARY_BACKEND=https://us-central1-excalidraw-room-persistence.cloudfunctions.net/libraries/
+REACT_APP_STORAGE_BACKEND=http
+REACT_APP_HTTP_STORAGE_BACKEND_URL=http://localhost:3003/api/v2 # to Excalidraw-Storage-Backend
+REACT_APP_WS_SERVER_URL=http://localhost:3002 # to Excalidraw-Room
+REACT_APP_PORTAL_URL='' # THIS NEED TO BE LEFT BLANK
+EXCALIDRAW_NODE_ENV=production
diff --git a/scripts/proxy/.env.example b/scripts/proxy/.env.example
@@ -1,4 +1,10 @@
+#
+# Override settings here.
+#
+
+#
 # CTFHub
+#
 CTFHUB_DEBUG=0                                            # Change here
 CTFHUB_HOSTNAME=ctfhub.mydomain.com                       # Change here to your server public IP / FQDN
 CTFHUB_PORT=443                                           # Change here to your server public port for CTFHub
@@ -20,20 +26,7 @@ POSTGRES_DB=ctfhub                                        # (opt.) Change here
 POSTGRES_USER=ctfhub                                      # (opt.) Change here
 POSTGRES_PASSWORD=tookahlaiphee2KieTeeg5ooxutang4o        # Change here
 
-# Excalidraw stack
-REACT_APP_BACKEND_V2_GET_URL=https://excalidraw.mydomain.com/api/v2/scenes/
-REACT_APP_BACKEND_V2_POST_URL=https://excalidraw.mydomain.com/api/v2/scenes/
-REACT_APP_LIBRARY_URL=https://libraries.excalidraw.com
-REACT_APP_LIBRARY_BACKEND=https://us-central1-excalidraw-room-persistence.cloudfunctions.net/libraries/
-REACT_APP_STORAGE_BACKEND=http
-REACT_APP_HTTP_STORAGE_BACKEND_URL=https://excalidraw.mydomain.com/api/v2
-REACT_APP_WS_SERVER_URL=https://collab.excalidraw.mydomain.com
-REACT_APP_PORTAL_URL=                                     # THIS NEED TO BE LEFT BLANK
-
-# Redis
-REDIS_PASSWORD=redis123                                   # Change here
-
-# hedgedoc
+# Hedgedoc
 CMD_DOMAIN=hedgedoc.mydomain.com
 CMD_URL_ADDPORT=false
 CMD_PORT=
diff --git a/scripts/proxy/conf/nginx/nginx.conf b/scripts/proxy/conf/nginx/nginx.conf
diff --git a/scripts/proxy/docker-compose.yml b/scripts/proxy/docker-compose.yml
