diff options
author | 2021-06-27 16:13:01 +0800 | |
---|---|---|
committer | 2021-06-27 16:13:01 +0800 | |
commit | 5b64d1f445f7dee65533811e024ca04a96782c1b (patch) | |
tree | dd1d389ba271371d6a3143dc80426b5f680407e5 | |
parent | Merge pull request #536 from bast0006/fix-nitro-message (diff) | |
parent | Merge branch 'main' into move-config-docs-to-contributing-guide (diff) |
Merge pull request #523 from python-discord/move-config-docs-to-contributing-guide
Move config docs to contributing guide, kill `docs` directory.
-rw-r--r-- | docs/README.md | 17 | ||||
-rw-r--r-- | docs/configuration.md | 25 | ||||
-rw-r--r-- | docs/setup.md | 91 | ||||
-rw-r--r-- | pydis_site/apps/content/resources/guides/pydis-guides/contributing/site.md | 36 |
4 files changed, 36 insertions, 133 deletions
diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index 5af383b4..00000000 --- a/docs/README.md +++ /dev/null @@ -1,17 +0,0 @@ -# Documentation - -This directory contains useful documentation for working with and using our site. - -## Table of contents - -* [Setup guide](setup.md) - - * [PostgreSQL setup](setup.md#postgresql-setup) - - * [Development with Docker](setup.md#development-with-docker) - - * [Development with `pip`](setup.md#development-with-pip) - -> Note: If you're looking to add redirects to the site, the `redirects` app is **NOT** the way to go. -> Convenience redirects should use our [Cloudflare Worker](https://github.com/python-discord/workers/tree/main/short-urls). -> Ask in the server if you have any questions! diff --git a/docs/configuration.md b/docs/configuration.md deleted file mode 100644 index 037f029f..00000000 --- a/docs/configuration.md +++ /dev/null @@ -1,25 +0,0 @@ -# Configuration -The website is configured through the following environment variables: - -## Essential -- **`DATABASE_URL`**: A string specifying the PostgreSQL database to connect to, - in the form `postgresql://user:password@host/database`, such as - `postgresql://joethedestroyer:ihavemnesia33@localhost/pysite_dev` - -- **`DEBUG`**: Controls Django's internal debugging setup. Enable this when - you're developing locally. Optional, defaults to `False`. - -- **`LOG_LEVEL`**: Any valid Python `logging` module log level - one of `DEBUG`, - `INFO`, `WARN`, `ERROR` or `CRITICAL`. When using debug mode, this defaults to - `INFO`. When testing, defaults to `ERROR`. Otherwise, defaults to `WARN`. - -## Deployment -- **`ALLOWED_HOSTS`**: A comma-separated lists of alternative hosts to allow to - host the website on, when `DEBUG` is not set. Optional, defaults to the - `pythondiscord.com` family of domains. - -- **`SECRET_KEY`**: The secret key used in various parts of Django. Keep this - secret as the name suggests! This is managed for you in debug setups. - -- **`STATIC_ROOT`**: The root in which `python manage.py collectstatic` collects - static files. Optional, defaults to `/var/www/pythondiscord.com`. diff --git a/docs/setup.md b/docs/setup.md deleted file mode 100644 index d88021cc..00000000 --- a/docs/setup.md +++ /dev/null @@ -1,91 +0,0 @@ -# Setup - -Setting up the Python site for local development -is quick and easy using `pip`. -Alternatively, you can set it up using Docker. -Both of these methods are documented here. - -## PostgreSQL setup - -Install PostgreSQL according to its documentation. -Then, create databases and users: - -```sql -$ psql -qd postgres -postgres=# CREATE USER pysite WITH CREATEDB; -postgres=# CREATE DATABASE pysite OWNER pysite; -``` - -Using different databases for development -and tests is recommended because Django -will expect an empty database when running tests. -Now that PostgreSQL is set up, simply set the proper database URL -in your environment variables: - -```sh -export DATABASE_URL=postgres://pysite@localhost/pysite -``` - -After this step, inside the `.env` file, set the `SECRET_KEY` variable which can be anything you like. - -A simpler approach to automatically configuring this might come in the -near future - if you have any suggestions, please let us know! - -## Development with Docker - -To quickly set up the site locally, you can use Docker. -You will need Docker itself and `docker-compose` - -you can omit the latter if you want to use PostgreSQL on -your host. Refer to the docker documentation on how to install Docker. - -If you want to set the site up using `docker-compose`, simply run - -```sh -docker-compose up -``` - -and it will do its magic. - -Otherwise, you need to set a bunch of environment variables (or pass them along to -the container). You will also need to have a running PostgreSQL instance if you want -to run on your host's PostgreSQL instance. - -## Development with `pip` - -This is the recommended way if you wish to quickly test your changes and don't want -the overhead that Docker brings. - -Follow the PostgreSQL setup instructions above. Then, create a virtual environment -for the project. If you're new to this, you may want to check out [Installing packages -using pip and virtualenv](https://packaging.python.org/guides/installing-using-pip-and-virtualenv/) -from the Python Packaging User Guide. - -Enter the virtual environment. Now you can run - -```sh -pip install -e .[lint,test] -``` - -to install base dependencies along with lint and test dependencies. - -To run tests, use `python manage.py test`. - -## Hosts file - -Make sure you add the following to your hosts file: - -```sh -127.0.0.1 pythondiscord.local -127.0.0.1 api.pythondiscord.local -127.0.0.1 staff.pythondiscord.local -127.0.0.1 admin.pythondiscord.local -``` -When trying to access the site, you'll be using the domains above instead of the usual `localhost:8000`. - -Finally, you will need to set the environment variable `DEBUG=1`. If you have `python-dotenv` installed, you can put this into a - `.env` file to have it exported automatically. It's also recommended to -export `LOG_LEVEL=INFO` when using `DEBUG=1` if you don't want super verbose logs. - -To run the server, run `python manage.py runserver`. If it gives you an error saying -`django.core.exceptions.ImproperlyConfigured: Set the DATABASE_URL environment variable` please make sure the server that your postgres database is located at is running -and run the command `$(export cat .env)`. Happy hacking! diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/site.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/site.md index ada47931..24227f24 100644 --- a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/site.md +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/site.md @@ -79,6 +79,9 @@ SECRET_KEY=suitable-for-development-only STATIC_ROOT=staticfiles ``` +The [Configuration in Detail](#configuration-in-detail) section contains +detailed information about these settings. + #### Notes regarding `DATABASE_URL` - If the database is hosted locally i.e. on the same machine as the webserver, then use `localhost` for the host. Windows and macOS users may need to use the [Docker host IP](../hosts-file/#windows) instead. @@ -143,3 +146,36 @@ Unless you are editing the Dockerfile or docker-compose.yml, you shouldn't need Django provides an interface for administration with which you can view and edit the models among other things. It can be found at [http://admin.pythondiscord.local:8000](http://admin.pythondiscord.local:8000). The default credentials are `admin` for the username and `admin` for the password. + +--- + +# Configuration in detail + +The website is configured through the following environment variables: + +## Essential +- **`DATABASE_URL`**: A string specifying the PostgreSQL database to connect to, + in the form `postgresql://user:password@host/database`, such as + `postgresql://joethedestroyer:ihavemnesia33@localhost/pysite_dev` + +- **`METRICITY_DB_URL`**: A string specifying the PostgreSQL metric database to + connect to, in the same form as `$DATABASE_URL`. + +- **`DEBUG`**: Controls Django's internal debugging setup. Enable this when + you're developing locally. Optional, defaults to `False`. + +- **`LOG_LEVEL`**: Any valid Python `logging` module log level - one of `DEBUG`, + `INFO`, `WARN`, `ERROR` or `CRITICAL`. When using debug mode, this defaults to + `INFO`. When testing, defaults to `ERROR`. Otherwise, defaults to `WARN`. + +## Deployment +- **`ALLOWED_HOSTS`**: A comma-separated lists of alternative hosts to allow to + host the website on, when `DEBUG` is not set. Optional, defaults to the + `pythondiscord.com` family of domains. + +- **`SECRET_KEY`**: The secret key used in various parts of Django. Keep this + secret as the name suggests! This is managed for you in debug setups. + +- **`STATIC_ROOT`**: The root in which `python manage.py collectstatic` + collects static files. Optional, defaults to `/app/staticfiles` for the + standard Docker deployment. |