Merge branch 'master' into refactor/auth-ts

chen-robert · web-flow · commit 85edaa365cf9 · 2020-08-05T21:02:59.000-07:00
diff --git a/.gitignore b/.gitignore
@@ -9,6 +9,7 @@ yarn-error.log*
 /data
 /conf.d/*
 !/conf.d/.keep
+/docs/site
 
 # Upload provider dir
 /uploads
diff --git a/.readthedocs.yml b/.readthedocs.yml
diff --git a/README.md b/README.md
@@ -2,7 +2,7 @@
 
 [![Build Status](https://github.com/redpwn/rCTF/workflows/CI/badge.svg?branch=master)](https://github.com/redpwn/rCTF/actions?query=workflow%3ACI+branch%3Amaster)
 [![Code Coverage](https://img.shields.io/codecov/c/github/redpwn/rctf.svg)](https://codecov.io/github/redpwn/rctf/)
-[![Docs](https://img.shields.io/readthedocs/rctf/latest)](https://rctf.redpwn.net/)
+[![Netlify Status](https://api.netlify.com/api/v1/badges/ae459ed6-1a84-43ff-b113-5561f3e4bd82/deploy-status)](https://rctf.redpwn.net)
 
 rCTF is redpwnCTF's CTF platform. It is developed and maintained by the [redpwn](https://redpwn.net) CTF team.
 
diff --git a/docs/content/configuration.md b/docs/content/configuration.md
@@ -35,8 +35,50 @@ meta:
 
 ## Configuration
 
+### Core 
+
+Important values to configure to customize your CTF. 
+
 YAML/JSON name|environment name|required|default value|type|description
 -|-|-|-|-|-
+`ctfName`|`RCTF_NAME`|yes|_(none)_|string|name of the CTF throughout the UI
+`meta.description`|`RCTF_META_DESCRIPTION`|yes|`''`|string|OpenGraph and Twitter embed description
+`meta.imageUrl`|`RCTF_IMAGE_URL`|yes|`''`|string|OpenGraph and Twitter embed image URL
+`origin`|`RCTF_ORIGIN`|yes|_(none)_|string|public URL of the rCTF instance
+`homeContent`|`RCTF_HOME_CONTENT`|yes|`''`|string|markdown content for the homepage of the CTF. [documentation](management/home.md)
+`startTime`|`RCTF_START_TIME`|yes|_(none)_|integer|time at which the CTF starts, in milliseconds since the epoch
+`endTime`|`RCTF_END_TIME`|yes|_(none)_|integer|time at which the CTF ends, in milliseconds since the epoch
+`divisions`|_(none)_|yes|_(none)_|object|division IDs and their respective names. [documentation](management/divisions.md)
+`defaultDivision`|_(none)_|no|_(none)_|string|default division ID. [documentation](management/divisions.md)
+`divisionACLs`|_(none)_|no|_(none)_|array|ACLs for restricting division access. [documentation](management/divisions.md)
+
+### Additional
+
+Optional configuration to enable additional features. 
+
+YAML/JSON name|environment name|required|default value|type|description
+-|-|-|-|-|-
+`sponsors`|_(none)_|yes|`[]`|array|list of CTF sponsors. [documentation](management/home.md)
+`globalSiteTag`|`RCTF_GLOBAL_SITE_TAG`|no|_(none)_|string|Google Analytics site tag
+`logoUrl`|`RCTF_LOGO_URL`|no|_(none)_|string|URL to raster image of the CTF's logo. used in emails
+`email.provider`|_(none)_|no|_(none)_|provider|provider for email sending. [documentation](providers/emails/index.md)
+`email.from`|_(none)_|no|_(none)_|provider|`from:` address when sending email. [documentation](providers/emails/index.md)
+`ctftime.clientId`|`RCTF_CTFTIME_CLIENT_ID`|no|_(none)_|string|CTFtime OAuth client ID. [documentation](integrations/ctftime.md)
+`ctftime.clientSecret`|`RCTF_CTFTIME_CLIENT_SECRET`|no|_(none)_|string|CTFtime OAuth client secret. [documentation](integrations/ctftime.md)
+
+### Advanced
+
+Configuration for advanced users - sane defaults are automatically set by the installation script. 
+
+YAML/JSON name|environment name|required|default value|type|description
+-|-|-|-|-|-
+`tokenKey`|`RCTF_TOKEN_KEY`|yes|_(none)_|string|base64 encoded 32 byte key used for encrypting tokens
+`loginTimeout`|`RCTF_LOGIN_TIMEOUT`|yes|3600000|integer|lifetime of registration, email update, and recovery links, in milliseconds
+`userMembers`|`RCTF_USER_MEMBERS`|yes|`true`|boolean|whether to allow a user to provide emails for individual members 
+`database.migrate`|`RCTF_DATABASE_MIGRATE`|yes|`never`|`before | only | never`|how to run postgreSQL migrations. [documentation](management/migration.md)
+`instanceType`|`RCTF_INSTANCE_TYPE`|yes|`all`|`all | frontend | leaderboard`|what type of instance to run. [documentation](management/scaling.md)
+`challengeProvider`|_(none)_|yes|`database`|provider|provider for challenges. [documentation](providers/challenges/index.md)
+`uploadProvider`|_(none)_|yes|`local`|provider|provider for challenge file uploads. [documentation](providers/uploads/index.md)
 `database.sql`|`RCTF_DATABASE_URL`|either `database.sql` or `database.sql.*`|_(none)_|string|`postgres://` connection URI
 `database.sql.host`|`RCTF_DATABASE_HOST`|either `database.sql` or `database.sql.*`|_(none)_|string|hostname of a postgreSQL server
 `database.sql.port`|`RCTF_DATABASE_PORT`|either `database.sql` or `database.sql.*`|_(none)_|string|port number that postgreSQL is running on
@@ -48,38 +90,12 @@ YAML/JSON name|environment name|required|default value|type|description
 `database.redis.post`|`RCTF_REDIS_PORT`|either `database.sql` or `database.sql.*`|_(none)_|string|port number that redis is running on
 `database.redis.password`|`RCTF_REDIS_PASSWORD`|either `database.sql` or `database.sql.*`|_(none)_|string|redis password to authenticate with
 `database.redis.database`|`RCTF_REDIS_DATABASE`|either `database.sql` or `database.sql.*`|_(none)_|string|redis numerical database ID to use
-`database.migrate`|`RCTF_DATABASE_MIGRATE`|yes|`never`|`before | only | never`|how to run postgreSQL migrations. [See migration doc for more](../management/migration)
-`instanceType`|`RCTF_INSTANCE_TYPE`|yes|`all`|`all | frontend | leaderboard`|what type of instance to run. [See scaling doc for more](../management/scaling)
-`tokenKey`|`RCTF_TOKEN_KEY`|yes|_(none)_|string|base64 encoded 32 byte key used for encrypting tokens
-`origin`|`RCTF_ORIGIN`|yes|_(none)_|string|public URL of the rCTF instance
-`ctftime.clientId`|`RCTF_CTFTIME_CLIENT_ID`|no|_(none)_|string|CTFtime OAuth client ID. [See CTFtime doc for more](../integrations/ctftime)
-`ctftime.clientSecret`|`RCTF_CTFTIME_CLIENT_SECRET`|no|_(none)_|string|CTFtime OAuth client secret. [See CTFtime doc for more](../integrations/ctftime)
-`userMembers`|`RCTF_USER_MEMBERS`|yes|`true`|boolean|whether to allow a user to set emails for individual members
-`sponsors`|_(none)_|yes|`[]`|array|list of CTF sponsors. [See home doc for more](../management/home)
-`homeContent`|`RCTF_HOME_CONTENT`|yes|`''`|string|markdown content for the homepage of the CTF. [See home doc for more](../management/home)
-`ctfName`|`RCTF_NAME`|yes|_(none)_|string|name of the CTF throughout the UI
-`meta.description`|`RCTF_META_DESCRIPTION`|yes|`''`|string|OpenGraph and Twitter embed description
-`meta.imageUrl`|`RCTF_IMAGE_URL`|yes|`''`|string|OpenGraph and Twitter embed image URL
-`logoUrl`|`RCTF_LOGO_URL`|no|_(none)_|string|URL to raster image of the CTF's logo. used in emails
-`globalSiteTag`|`RCTF_GLOBAL_SITE_TAG`|no|_(none)_|string|Google Analytics site tag
-`challengeProvider`|_(none)_|yes|`database`|provider|provider for challenges. [See challenge provider doc for more](../providers/challenges/index)
-`uploadProvider`|_(none)_|yes|`local`|provider|provider for challenge file uploads. [See upload provider doc for more](../providers/uploads/index)
-`email.provider`|_(none)_|no|_(none)_|provider|provider for email sending. [See email doc for more](../providers/emails/index)
-`email.from`|_(none)_|no|_(none)_|provider|`from:` address when sending email. [See email doc for more](../providers/emails/index)
-`divisions`|_(none)_|yes|_(none)_|object|division IDs and their respective names. [See division doc for more](../management/divisions)
-`defaultDivision`|_(none)_|no|_(none)_|string|default division ID. [See division doc for more](../management/divisions)
-`divisionACLs`|_(none)_|no|_(none)_|array|ACLs for restricting division access. [See division doc for more](../management/divisions)
-`startTime`|`RCTF_START_TIME`|yes|_(none)_|integer|time at which the CTF starts, in milliseconds since the epoch
-`endTime`|`RCTF_END_TIME`|yes|_(none)_|integer|time at which the CTF ends, in milliseconds since the epoch
 `leaderboard.maxLimit`|`RCTF_LEADERBOARD_MAX_LIMIT`|yes|100|integer|maximum number of users retrievable in a single leaderboard request
 `leaderboard.maxOffset`|`RCTF_LEADERBOARD_MAX_OFFSET`|yes|4294967296|integer|maximum offset from the beginning of the leaderboard
 `leaderboard.updateInterval`|`RCTF_LEADERBOARD_UPDATE_INTERVAL`|yes|10000|integer|interval at which the leaderboard is recalculated, in milliseconds
 `leaderboard.graphMaxTeams`|`RCTF_LEADERBOARD_GRAPH_MAX_TEAMS`|yes|10|integer|maximum number of users retrievable in a graph request
 `leaderboard.graphSampleTime`|`RCTF_LEADERBOARD_GRAPH_SAMPLE_TIME`|yes|1800000|integer|interval at which the score graph is sampled, in milliseconds
-`loginTimeout`|`RCTF_LOGIN_TIMEOUT`|yes|3600000|integer|lifetime of registration, email update, and recovery links, in milliseconds
 
 ## Custom `conf.d` location
 
-The `conf.d` directory can be renamed or moved elsewhere.
-
-To do so, set the `RCTF_CONF_PATH` environment variable to the location of a directory of YAML or JSON configuration files. If specified as a relative path, the path is evaluated from the current working directory.
+The `conf.d` directory can be renamed or moved elsewhere. To do so, set the `RCTF_CONF_PATH` environment variable to the location of a directory of YAML or JSON configuration files. If specified as a relative path, the path is evaluated from the current working directory.
diff --git a/docs/content/development/manual-installation.md b/docs/content/development/manual-installation.md
@@ -2,29 +2,23 @@
 
 Manual installation of rCTF is useful to develop and modify the project.
 
-If you want to install rCTF on your local machine, you will need `yarn` installed. rCTF currently targets node 12, so you should either install that version locally or use nvm, for example with `nvm use --delete-prefix v12.16.1`. 
+To run rCTF locally, you'll need [node](https://nodejs.org/) and [yarn](https://yarnpkg.com/).
 
-```shell
-git clone https://github.com/redpwn/rCTF.git && cd rCTF
+Clone the rCTF repository:
+```bash
+git clone https://github.com/redpwn/rctf
 ```
 
-After cloning, you will need to setup the configuration files.
-
-```shell
-cp -nR config/yml.example config/yml
-cp .env.example .env
-```
-
-Before you run rCTF for the first time, set the [mandatory configuration options](../configuration.md#configuration-options).
+After cloning, you will need to setup the configuration files in the `conf.d` directory. [An example `conf.d`](https://github.com/redpwn/rctf/blob/master/test/conf-test.yaml) is used for testing.
 
 To develop rCTF, run:
 
-```shell
+```bash
 yarn dev
 ```
 
 To simulate a full production build, run:
 
-```shell
+```bash
 yarn build && yarn start
 ``` 
diff --git a/docs/content/index.md b/docs/content/index.md
@@ -2,3 +2,5 @@
 
 rCTF is redpwnCTF's CTF platform. It is developed and maintained by the
 [redpwn](https://redpwn.net) CTF team.
+
+To install rCTF, see [the installation doc](installation.md).
diff --git a/docs/content/installation.md b/docs/content/installation.md
@@ -5,3 +5,11 @@ You can install rCTF in one command with [the installer script](https://get.rctf
 ```bash
 curl https://get.rctf.redpwn.net | sh
 ```
+
+## After installation
+
+To configure rCTF, see [the configuration doc](configuration.md).
+
+To update the CTF's challenges, see [the admin doc](management/admin.md).
+
+To scale up rCTF, see the [migration](management/migration.md) and [scaling](management/scaling.md) docs.
diff --git a/docs/content/management/admin.md b/docs/content/management/admin.md
@@ -0,0 +1,13 @@
+# Challenge Admin
+
+rCTF integrates with [rCDS](https://github.com/redpwn/rcds), which can automatically deploy challenges and sync them to rCTF.
+
+To use rCTF without rCDS, create an admin user normally. Then, connect to postgreSQL and run:
+```sql
+UPDATE users SET perms=3 WHERE id='your user id';
+```
+
+After running, you can manage the CTF's challenges using a web UI at:
+```
+https://your-rctf.example.com/admin/challs
+```
diff --git a/docs/content/management/divisions.md b/docs/content/management/divisions.md
@@ -8,6 +8,7 @@ Every user must be in exactly one division, although users can change their divi
 * `divisionACLs` is a priority list of ACL elements. Only one element matches an email at a time, and each element contains `match`, `value`, and an allowed `divisions` list. If the `divisions` list contains multiple elements, the first element is used while registering.
 
 Possible `match` values are:
+
 * `domain`: The `value` contains a domain which the user's email must be from.
 * `email`: The `value` contains an exact email which the user's must match.
 * `regex`: The `value` contains a RegEx used to match the user's domain.
diff --git a/docs/content/management/scaling.md b/docs/content/management/scaling.md
@@ -1,6 +1,7 @@
 # Scaling
 
 rCTF can be split into two types of instances.
+
 * Frontend instances are horizontally scalable and handle incoming requests
 * A single leaderboard instance does leaderboard and graph data calculations.
 
diff --git a/docs/content/providers/challenges/database.md b/docs/content/providers/challenges/database.md
@@ -1,6 +1,6 @@
 # Database Challenge Provider
 
-The database challenge provider stores challenge details in the Postgresql database. To use it, specify `challenges/database` for the challenge provider name.
+The database challenge provider stores challenge details in the postgreSQL database. To use it, specify `challenges/database` for the challenge provider name.
 
 ## Configuration Example
 
diff --git a/docs/content/providers/challenges/index.md b/docs/content/providers/challenges/index.md
@@ -1,3 +1,5 @@
 # Challenge Provider Index
 
-Challenge providers store the list of challenges in the CTF. At the moment, only the [database challenge provider](database) is available.
+Challenge providers store the list of challenges in the CTF. At the moment, there is one challenge provider available:
+
+* [Database](database.md)
diff --git a/docs/content/providers/emails/index.md b/docs/content/providers/emails/index.md
@@ -1,6 +1,7 @@
 # Email Provider Index
 
-Email providers send emails to competitors. In rCTF, Emails are used for registration, email updates, and recovery. At the moment, there are three email providers available:
-* [Mailgun](mailgun)
-* [SES](ses)
-* [SMTP](smtp)
+Email providers send emails to competitors. In rCTF, emails are used for registration, email updates, and recovery. At the moment, there are three email providers available:
+
+* [Mailgun](mailgun.md)
+* [SES](ses.md)
+* [SMTP](smtp.md)
diff --git a/docs/content/providers/uploads/index.md b/docs/content/providers/uploads/index.md
@@ -1,5 +1,6 @@
 # Upload Provider Index
 
 Upload providers store files for each challenge. At the moment, there are two upload providers available:
-* [Google Cloud Storage](gcs)
-* [Local](local)
+
+* [Google Cloud Storage](gcs.md)
+* [Local](local.md)
diff --git a/docs/content/providers/uploads/local.md b/docs/content/providers/uploads/local.md
@@ -9,7 +9,7 @@ rCTF must have write access to the `uploadDirectory`.
 Option|Description
 -|-
 `uploadDirectory`|The directory where uploaded files are stored. (default: `uploads`)
-`endpoint`|The endpoint from which uploaded files are served. Unless (default: `/uploads`)
+`endpoint`|The endpoint from which uploaded files are served. (default: `/uploads`)
 
 ## Configuration Example
 
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
@@ -3,6 +3,35 @@ site_description: rCTF Documentation
 site_author: redpwn
 site_url: https://rctf.redpwn.net
 
+nav:
+  - Home: index.md
+  - Installation: installation.md
+  - Configuration: configuration.md
+  - Management:
+    - Admin: management/admin.md
+    - Home: management/home.md
+    - Divisions: management/divisions.md
+    - Migration: management/migration.md
+    - Scaling: management/scaling.md
+  - Providers:
+    - Index: providers/index.md
+    - Challenges:
+      - Index: providers/challenges/index.md
+      - Database: providers/challenges/database.md
+    - Emails:
+      - Index: providers/emails/index.md
+      - Mailgun: providers/emails/mailgun.md
+      - SES: providers/emails/ses.md
+      - SMTP: providers/emails/smtp.md
+    - Uploads:
+      - Index: providers/uploads/index.md
+      - GCS: providers/uploads/gcs.md
+      - Local: providers/uploads/local.md
+  - Integrations:
+    - CTFtime: integrations/ctftime.md
+  - Development:
+    - Manual Installation: development/manual-installation.md
+
 repo_name: GitHub
 repo_url: https://github.com/redpwn/rctf
 edit_uri: blob/master/docs/content/
@@ -12,6 +41,8 @@ docs_dir: content
 theme:
   name: material
   language: en
+  features: 
+    - instant
   palette:
     scheme: slate
     primary: blue
diff --git a/docs/runtime.txt b/docs/runtime.txt
@@ -0,0 +1 @@
+3.7
