Skip to content

Commit ac236e2

Browse files
ColdHeatColdHeat
authored
Docs (CTFd#1001)
* Copy over and update content from the Wiki to CTFd Sphinx docs * Closes CTFd#947 * Closes CTFd#742
1 parent 49b48a9 commit ac236e2

9 files changed

+778
-7
lines changed

‎development.txt

+1
Original file line numberDiff line numberDiff line change
@@ -13,3 +13,4 @@ bandit==1.5.1
1313
flask_profiler==1.8.1
1414
pytest-xdist==1.28.0
1515
pytest-cov==2.6.1
16+
sphinx_rtd_theme==0.4.3

‎docs/api.rst

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
API
2+
===

‎docs/conf.py

+4-4
Original file line numberDiff line numberDiff line change
@@ -20,13 +20,13 @@
2020
# -- Project information -----------------------------------------------------
2121

2222
project = u'CTFd'
23-
copyright = u'2019, Kevin Chung'
23+
copyright = u'2019, CTFd LLC'
2424
author = u'Kevin Chung'
2525

2626
# The short X.Y version
2727
version = u''
2828
# The full version, including alpha/beta/rc tags
29-
release = u'2.1.0'
29+
release = u'2.1.2'
3030

3131

3232
# -- General configuration ---------------------------------------------------
@@ -78,7 +78,7 @@
7878
# The theme to use for HTML and HTML Help pages. See the documentation for
7979
# a list of builtin themes.
8080
#
81-
html_theme = 'alabaster'
81+
html_theme = 'sphinx_rtd_theme'
8282

8383
# Theme options are theme-specific and customize the look and feel of a theme
8484
# further. For a list of options available for each theme, see the
@@ -154,7 +154,7 @@
154154
# dir menu entry, description, category)
155155
texinfo_documents = [
156156
(master_doc, 'CTFd', u'CTFd Documentation',
157-
author, 'CTFd', 'One line description of project.',
157+
author, 'CTFd', 'A Capture The Flag framework focusing on ease of use and customizability.',
158158
'Miscellaneous'),
159159
]
160160

‎docs/configuration.rst

+147
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
Configuration
2+
=============
3+
4+
CTFd provides a number of configuration options which are used to configure server behavior. CTFd makes a distinction between configuration values which can be configured only with server-level access and values which can be configured by those with administrative priveleges on CTFd.
5+
6+
Server Level Configuration
7+
--------------------------
8+
Server level configuration can be modified from the ``config.py`` file in CTFd.
9+
10+
SECRET_KEY
11+
~~~~~~~~~~
12+
The secret value used to creation sessions and sign strings. This should be set to a random string. In the
13+
interest of ease, CTFd will automatically create a secret key file for you. If you wish to add this secret key
14+
to your instance you should hard code this value to a random static value.
15+
16+
You can also remove .ctfd_secret_key from the .gitignore file and commit this file into whatever repository
17+
you are using.
18+
19+
http://flask.pocoo.org/docs/latest/quickstart/#sessions
20+
21+
22+
DATABASE_URL
23+
~~~~~~~~~~~~
24+
The URI that specifies the username, password, hostname, port, and database of the server
25+
used to hold the CTFd database.
26+
27+
e.g. ``mysql+pymysql://root:<YOUR_PASSWORD_HERE>@localhost/ctfd``
28+
29+
REDIS_URL
30+
~~~~~~~~~
31+
The URI to connect to a Redis server.
32+
33+
e.g. ``redis://user:password@localhost:6379``
34+
35+
http://pythonhosted.org/Flask-Caching/#configuring-flask-caching
36+
37+
38+
MAILFROM_ADDR
39+
~~~~~~~~~~~~~
40+
The email address that emails are sent from if not overridden in the configuration panel.
41+
42+
MAIL_SERVER
43+
~~~~~~~~~~~
44+
The mail server that emails are sent from if not overriden in the configuration panel.
45+
46+
MAIL_PORT
47+
~~~~~~~~~
48+
The mail port that emails are sent from if not overriden in the configuration panel.
49+
50+
MAIL_USEAUTH
51+
~~~~~~~~~~~~
52+
Whether or not to use username and password to authenticate to the SMTP server
53+
54+
MAIL_USERNAME
55+
~~~~~~~~~~~~~
56+
The username used to authenticate to the SMTP server if MAIL_USEAUTH is defined
57+
58+
MAIL_PASSWORD
59+
~~~~~~~~~~~~~
60+
The password used to authenticate to the SMTP server if MAIL_USEAUTH is defined
61+
62+
MAIL_TLS
63+
~~~~~~~~
64+
Whether to connect to the SMTP server over TLS
65+
66+
MAIL_SSL
67+
~~~~~~~~
68+
Whether to connect to the SMTP server over SSL
69+
70+
MAILGUN_API_KEY
71+
~~~~~~~~~~~~~~~
72+
Mailgun API key to send email over Mailgun
73+
74+
MAILGUN_BASE_URL
75+
~~~~~~~~~~~~~~~~
76+
Mailgun base url to send email over Mailgun
77+
78+
LOG_FOLDER
79+
~~~~~~~~~~
80+
The location where logs are written. These are the logs for CTFd key submissions, registrations, and logins.
81+
The default location is the CTFd/logs folder.
82+
83+
UPLOAD_PROVIDER
84+
~~~~~~~~~~~~~~~
85+
Specifies the service that CTFd should use to store files.
86+
87+
UPLOAD_FOLDER
88+
~~~~~~~~~~~~~
89+
The location where files are uploaded. The default destination is the CTFd/uploads folder.
90+
91+
AWS_ACCESS_KEY_ID
92+
~~~~~~~~~~~~~~~~~
93+
AWS access token used to authenticate to the S3 bucket.
94+
95+
AWS_SECRET_ACCESS_KEY
96+
~~~~~~~~~~~~~~~~~~~~~
97+
AWS secret token used to authenticate to the S3 bucket.
98+
99+
AWS_S3_BUCKET
100+
~~~~~~~~~~~~~
101+
The unique identifier for your S3 bucket.
102+
103+
AWS_S3_ENDPOINT_URL
104+
~~~~~~~~~~~~~~~~~~~
105+
A URL pointing to a custom S3 implementation.
106+
107+
108+
REVERSE_PROXY
109+
~~~~~~~~~~~~~
110+
Specifies whether CTFd is behind a reverse proxy or not. Set to ``True`` if using a reverse proxy like nginx.
111+
112+
See `Flask documentation <https://werkzeug.palletsprojects.com/en/0.15.x/middleware/proxy_fix/#werkzeug.middleware.proxy_fix.ProxyFix.>`_ for full details.
113+
114+
.. Tip::
115+
You can also specify a comma seperated set of numbers specifying the reverse proxy configuration settings. For example to configure `x_for=1, x_proto=1, x_host=1, x_port=1, x_prefix=1` specify `1,1,1,1,1`. By setting the value to ``True``, CTFd will default to the above behavior with all proxy settings set to 1.
116+
117+
TEMPLATES_AUTO_RELOAD
118+
~~~~~~~~~~~~~~~~~~~~~
119+
Specifies whether Flask should check for modifications to templates and reload them automatically.
120+
121+
SQLALCHEMY_TRACK_MODIFICATIONS
122+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
123+
Automatically disabled to suppress warnings and save memory. You should only enable this if you need it.
124+
125+
SWAGGER_UI
126+
~~~~~~~~~~
127+
Enable the Swagger UI endpoint at ``/api/v1/``
128+
129+
UPDATE_CHECK
130+
~~~~~~~~~~~~
131+
Specifies whether or not CTFd will check whether or not there is a new version of CTFd
132+
133+
APPLICATION_ROOT
134+
~~~~~~~~~~~~~~~~
135+
Specifies what path CTFd is mounted under. It can be used to run CTFd in a subdirectory.
136+
Example: /ctfd
137+
138+
OAUTH_CLIENT_ID
139+
~~~~~~~~~~~~~~~
140+
141+
142+
OAUTH_CLIENT_SECRET
143+
~~~~~~~~~~~~~~~~~~~
144+
145+
146+
Application Level Configuration
147+
-------------------------------

‎docs/contributing.rst

+86
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
Contributing
2+
============
3+
4+
Developing on CTFd
5+
~~~~~~~~~~~~~~~~~~
6+
Developing new code for CTFd is easy and fun! CTFd is organized into components which each serve a distinct purpose.
7+
8+
9+
Core Routes/Controllers
10+
-----------------------
11+
The core routes are identified in blueprints in the main CTFd folder for user facing routes and in the CTFd/admin folder for the admin panel. These core routes are used to display theme content and render the main server response that the user will receive.
12+
13+
API Routes/Controllers
14+
----------------------
15+
The API routes are implemented in the ``CTFd/api`` folder as seperate blueprints for each type of resource used in CTFd. Most behavior that manipulates data should be implemented at the API level and seperated by method and resource level. The most common API methods are ``GET``, ``POST``, ``PATCH``, ``DELETE``.
16+
17+
Models
18+
------
19+
CTFd makes heavy usage of the SQLAlchemy ORM to access database contents. The core CTFd models are defined here. Plugins are however capable of adding their own models.
20+
21+
CTFd makes use of ``alembic`` and ``Flask-Migrate`` to perform database migrations between versions.
22+
23+
Schemas
24+
-------
25+
Schemas provide an abstraction layer on top of the database models for permissioning and filtering of data. Schemas and the API work together to make distinctions about what data to show users and what data a user can edit.
26+
27+
Jinja2
28+
------
29+
Jinja2 is used by the CTFd server to render HTML content with data. In some cases (i.e. JavaScript challenge rendering), Mozilla Nunjucks templates are used as a mostly compatible alternative. Any templates written in Nunjucks must still be compatible with Jinja2.
30+
31+
JavaScript & CSS
32+
----------------
33+
JavaScript & CSS are used to style the front end of CTFd.
34+
35+
36+
Linting
37+
~~~~~~~
38+
39+
Python
40+
------
41+
Python code in CTFd is linted with `flake8` and `black`.
42+
43+
Javascript & CSS
44+
----------------
45+
JavaScript and CSS are linted with `prettier`.
46+
47+
.. Tip::
48+
The recommendation is to integrate all linters into your editor as your changes will fail to pass if the lint checks fail. See the ``Makefile`` for ``make lint``
49+
50+
51+
Testing
52+
~~~~~~~
53+
54+
Python
55+
------
56+
57+
Python tests are run using ``pytest`` on Travis. To run the test suite you can run `make test`. By default tests run against sqlite but this can be configured by setting the `TESTING_DATABASE_URL` environment variable.
58+
59+
CTFd will support both Python 2 and 3 until Python 2's EOL in 2020.
60+
61+
Tests are run in parallel with ``pytest-xdist`` and each test is run in its own database.
62+
63+
64+
Documentation
65+
~~~~~~~~~~~~~
66+
67+
CTFd's documentation is written using Sphinx and hosted by `Read the Docs <https://readthedocs.org/>`_.
68+
69+
To build the documentation, you should go into the ``docs`` folder and run `make html`. The content output into the `docs/_build` folder will be the resulting hosted output.
70+
71+
72+
Tips & Tricks
73+
~~~~~~~~~~~~~
74+
Typically while developing CTFd, developers use the provided ``serve.py`` script or its ``make serve`` wrapper and access CTFd at ``http://localhost:4000``.
75+
76+
Very often you will need to generate testing data so that you can exercise CTFd's behavior. The included ``populate.py`` script will insert randomized testing data into the CTFd database.
77+
78+
The ``export.py`` script can be used to create a CTFd export on the command line.
79+
80+
The ``import.py`` script can be used to load in a CTFd export on the command line.
81+
82+
If you need to wipe CTFd completely, you should:
83+
84+
* delete the database (CTFd/ctfd.db by default)
85+
* empty the cache. By default it will be stored in the ``.data`` folder if Redis is unavailable
86+
* (optional) remove the contents of the `CTFd/uploads` folder

‎docs/deployment.rst

+108
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
Deployment
2+
==========
3+
4+
CTFd is a standard WSGI application so most if not all `Flask documentation`_ on deploying a Flask based application should apply. This page will focus on the recommended ways to deploy CTFd.
5+
6+
.. Important::
7+
Fully managed and maintained CTFd deployments are available at https://ctfd.io.
8+
9+
Docker
10+
------
11+
12+
CTFd provides automatically generated `Docker images`_ and one of the simplest means of deploying a CTFd instance is to use Docker Compose.
13+
14+
.. Caution:: While Docker can be a very simple means of deploying CTFd, it can make debugging and receiving support more complicated. Before deploying using Docker, be sure you have a cursory understanding of how Docker works.
15+
16+
1. Install `Docker`_
17+
2. Install `Docker Compose`_
18+
3. Clone the CTFd repository with ``git clone https://github.com/CTFd/CTFd.git``
19+
4. Modify the ``docker-compose.yml`` file from the repository to specify a ``SECRET_KEY`` environment for the CTFd service. ::
20+
21+
environment:
22+
- SECRET_KEY=<SPECIFY_RANDOM_VALUE>
23+
- UPLOAD_FOLDER=/var/uploads
24+
- LOG_FOLDER=/var/log/CTFd
25+
- DATABASE_URL=mysql+pymysql://root:ctfd@db/ctfd
26+
- REDIS_URL=redis://cache:6379
27+
- WORKERS=4
28+
29+
.. Tip::
30+
You can also run ``python -c "import os; f=open('.ctfd_secret_key', 'a+'); f.write(os.urandom(64)); f.close()"`` within the CTFd repo to generate a .ctfd_secret_key file.
31+
32+
5. Run ``docker-compose up``
33+
6. You should now be able to access CTFd at http://localhost:8000
34+
35+
.. Note::
36+
The default Docker Compose configuration files do not provide a reverse proxy server or configure SSL/TLS. This is left as an exercise to the reader by design.
37+
38+
Standard WSGI Deployment
39+
------------------------
40+
41+
As a web application, CTFd has a few dependencies which require installation.
42+
43+
1. WSGI server
44+
2. Database server
45+
3. Caching server
46+
47+
WSGI Server
48+
~~~~~~~~~~~
49+
50+
While CTFd is a standard WSGI application and most WSGI servers (e.g. gunicorn, UWSGI, waitress) will likely suffice, CTFd is most commonly deployed with gunicorn. This is because of its simplicity and reasonable performance. It is installed by default and used by other deployment methods discussed on this page. By default it is configured to use gevent as a worker class.
51+
52+
53+
Database Server
54+
~~~~~~~~~~~~~~~
55+
56+
CTFd makes use of SQLAlchemy and as such supports a number of SQL databases. As of CTFd 2.0, the recommended database type is MySQL. CTFd is tested and has been installed against SQLite, Postgres, and MariaDB but this could change in the future.
57+
58+
By default CTFd will create a SQLite database if no database server has been configured.
59+
60+
.. Note::
61+
CTFd makes use of the JSON data type. MySQL >= 5.7.8 implements a proper JSON type while MariaDB does not. Small differences like these could eventually result in CTFd only supporting a few database servers.
62+
63+
Caching Server
64+
~~~~~~~~~~~~~~
65+
66+
CTFd makes heavy use of caching servers to store configuration values, user sessions, and page content. It is important to deploy CTFd with a caching server. The preferred caching server option is Redis.
67+
68+
By default if no cache server is configured, CTFd will attempt to use the filesystem as a cache and store values in the ``.data`` folder. This type of caching is not very performant thus it is highly recommended that you configure a Redis server.
69+
70+
Vagrant
71+
-------
72+
73+
CTFd provides a basic Vagrantfile for use with Vagrant. To run using Vagrant run the following commands:
74+
75+
::
76+
77+
vagrant up
78+
79+
Visit http://localhost:8000 where CTFd will be running.
80+
81+
To access the internal gunicorn terminal session inside Vagrant run:
82+
83+
::
84+
85+
vagrant ssh
86+
tmux attach ctfd
87+
88+
.. Note::
89+
90+
CTFd's Vagrantfile is not commonly used and is only community supported
91+
92+
Debug Server
93+
------------
94+
95+
The absolute simplest way to deploy CTFd merely involves running `python serve.py` to start Flask's built-in debugging server. This isn't recommended for anything but debugging and should not be used for any kind of load. It is discussed here because the debugging server can make identifying bugs and misconfigurations easier. In addition, development mostly occurs using the debug server.
96+
97+
.. Important::
98+
CTFd makes every effort to be an easy to setup application.
99+
However, deploying CTFd for large amounts of users can be difficult.
100+
101+
Fully managed and maintained CTFd deployments are available at https://ctfd.io. If you're interested in a specialized CTFd deployment with custom features please `contact us <https://ctfd.io/contact/>`_.
102+
103+
104+
.. _Flask documentation: http://flask.pocoo.org/docs/latest/deploying/
105+
.. _Docker images: https://hub.docker.com/r/ctfd/ctfd/
106+
.. _Docker: https://docs.docker.com/install/
107+
.. _Docker Compose: https://docs.docker.com/compose/install/
108+
.. _contact us: https://ctfd.io/contact/

0 commit comments

Comments
 (0)