From 1fb93238c52ec48d68fe6bc4b295f92598fdc1fe Mon Sep 17 00:00:00 2001 From: Tanner Collin Date: Wed, 6 Apr 2022 23:32:24 +0000 Subject: [PATCH] Add markdown development docs --- apiserver/docs/source/dev.rst | 191 ------------------------- apiserver/docs/source/dev_apiserver.md | 17 ++- apiserver/docs/source/dev_running.md | 54 +++++++ apiserver/docs/source/dev_webclient.md | 39 +++++ apiserver/docs/source/index.rst | 3 +- 5 files changed, 107 insertions(+), 197 deletions(-) delete mode 100644 apiserver/docs/source/dev.rst create mode 100644 apiserver/docs/source/dev_running.md create mode 100644 apiserver/docs/source/dev_webclient.md diff --git a/apiserver/docs/source/dev.rst b/apiserver/docs/source/dev.rst deleted file mode 100644 index 63a6235..0000000 --- a/apiserver/docs/source/dev.rst +++ /dev/null @@ -1,191 +0,0 @@ -Development Setup -================= - -.. contents:: :depth: 3 - -This guide assumes you are on a Debian-based distro. - -Install dependencies: - -.. sourcecode:: bash - - $ sudo apt update - $ sudo apt install memcached - - # Python: - $ sudo apt install build-essential python3 python3-dev python3-pip python3-virtualenv - - # Yarn / nodejs: - # from https://yarnpkg.com/lang/en/docs/install/#debian-stable - $ curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add - - $ echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list - $ sudo apt update - $ sudo apt install yarn - -Clone the repo: - -.. sourcecode:: bash - - $ git clone https://github.com/Protospace/spaceport.git - $ cd spaceport - -API Server ----------- - -Create a venv, activate it, and install: - -.. sourcecode:: bash - - $ cd apiserver - $ virtualenv -p python3 env - $ source env/bin/activate - (env) $ pip install -r requirements.txt - -Edit ``apiserver/secrets.py.example`` and save it as ``apiserver/secrets.py``. - -Now setup Django and run it: - -.. sourcecode:: bash - - (env) $ python manage.py migrate --run-syncdb - (env) $ python manage.py createsuperuser --email admin@example.com --username admin - (env) $ DEBUG=true python manage.py runserver 0.0.0.0:8002 - -Django will now be running on port 8002, connect to localhost:8002 to test it. - -Import Old Portal Data (optional) -+++++++++++++++++++++++++++++++++ - -Place ``old_portal.sqlite3`` in the same directory as ``manage.py``. If you -don't have the old portal data, ignore this section. - -Place old member photo folders in ``old_photos/``, for example: ``old_photos/1685/photo.jpg``. - -.. sourcecode:: bash - - (env) $ bash gen_old_models.sh - (env) $ time python import_old_portal.py YYYY-MM-DD - -Pass the date of the portal scrape in as an argument to the script. - -Give it about 15 minutes to run. This will import old models into the new portal -database, ready to be linked to user's emails when they sign up. - -Testing -+++++++ - -There are unit tests in `apiserver/api/tests.py` that you can run with: - -.. sourcecode:: bash - - (env) $ python manage.py test - -Documentation -+++++++++++++ - -Compile this documentation: - -.. sourcecode:: bash - - (env) $ cd docs - (env) $ make html - -HTML files will be put in the `apiserver/docs/build/html` directory. - -Webclient ---------- - -.. sourcecode:: bash - - # In a different terminal - $ cd webclient - $ yarn install - $ yarn start - -The webclient will now be running on port 3000. Make changes and refresh to see them. - -Reverse Proxy -------------- - -Point a domain to the server and reverse proxy requests according to subdomain. - -Domains: `portal.example.com`, `api.portal.example.com`, `static.portal.example.com`, `docs.portal.example.com` should all be reverse proxied. - -Configure nginx (`/etc/nginx/sites-available/default`): - -.. sourcecode:: text - - server { - listen 80; - root /var/www/html; - index index.html index.htm; - - server_name portal.example.com; - - location / { - proxy_pass http://127.0.0.1:3000/; - proxy_set_header Host $http_host; - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_set_header X-Forwarded-Proto $scheme; - } - } - - server { - listen 80; - root /var/www/html; - index index.html index.htm; - - server_name api.portal.example.com; - - client_max_body_size 20M; - - location / { - add_header 'Access-Control-Allow-Origin' '*' always; - add_header 'Access-Control-Allow-Headers' 'content-type, authorization' always; - add_header 'Access-Control-Allow-Methods' 'HEAD,GET,POST,PUT,PATCH,DELETE' always; - add_header 'Access-Control-Max-Age' '86400' always; - proxy_pass http://127.0.0.1:8002/; - proxy_set_header Host $http_host; - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_set_header X-Forwarded-Proto $scheme; - } - } - - server { - listen 80; - root /home/you/spaceport/apiserver/data/static; - index index.html; - - server_name static.portal.example.com; - - location / { - add_header 'cache-control' 'max-age=2678400' always; - try_files $uri $uri/ =404; - } - } - - server { - listen 80; - root /home/you/spaceport/apiserver/docs/build/html; - index index.html; - - server_name docs.portal.example.com; - - location / { - try_files $uri $uri/ =404; - } - } - -HTTPS -+++++ - -Install certbot and run it: - -.. sourcecode:: bash - - $ sudo apt install certbot python3-certbot-nginx - $ sudo certbot --nginx - -Answer the prompts, enable redirect. diff --git a/apiserver/docs/source/dev_apiserver.md b/apiserver/docs/source/dev_apiserver.md index ddb5dae..1308ea2 100644 --- a/apiserver/docs/source/dev_apiserver.md +++ b/apiserver/docs/source/dev_apiserver.md @@ -1,7 +1,7 @@ # API Server Development Setup -This guide assumes you are using Debian GNU/Linux 10 or Ubuntu 20.04 LTS. If you -aren't, just spin up a VPN with the correct version. Things break if you don't. +This guide assumes you are using Debian GNU/Linux 11 or Ubuntu 20.04 LTS. If you +aren't, just spin up a VM with the correct version. Things break if you don't. ## Install Dependencies @@ -25,8 +25,11 @@ $ source env/bin/activate (env) $ pip install -r requirements.txt ``` +You need to make sure the Python virtual environment `(env)` is enabled whenever +you run the API server. + Copy the secrets file and optionally fill out values depending on which -[[integrations]] you wish to enable. +[[integrations]] you wish to enable. It runs fine by default. ``` (env) $ cp apiserver/secrets.py.example apiserver/secrets.py @@ -43,7 +46,8 @@ Set up the database: (env) $ python manage.py migrate ``` -Create a super user so you can manage who's director or staff: +Create a super user so you can manage who's a director or staff. This is a special +account and is not treated as a member. ``` (env) $ python manage.py createsuperuser --email admin@example.com --username admin @@ -55,6 +59,9 @@ Run the development server: ``` $ source env/bin/activate -(env) $ DEBUG=true python manage.py runserver +(env) $ DEBUG=true BINDALL=true python manage.py runserver 0.0.0.0:8000 ``` +The development server is now listening on port 8000. You can connect to it by +opening `http://:8000/` in your web browser. If it's running +locally, that would be [http://127.0.0.1:8000/](http://127.0.0.1:8000/). diff --git a/apiserver/docs/source/dev_running.md b/apiserver/docs/source/dev_running.md new file mode 100644 index 0000000..86f02d7 --- /dev/null +++ b/apiserver/docs/source/dev_running.md @@ -0,0 +1,54 @@ +# Running the Development Setup + +This document explains how to actually use Spaceport after you have the API +server and web client set up. + +It assumes the API server is running on [http://127.0.0.1:8000/](http://127.0.0.1:8000/) and the web +client is [http://127.0.0.1:3000/](http://127.0.0.1:3000/) you can replace `127.0.0.1` with whatever the +IP if your virtual machine or server is. + +## Register the First Member + +Open the web client [http://127.0.0.1:3000/](http://127.0.0.1:3000/) in your browser. + +Fill out the "Sign Up to Spaceport" form. If you see a "Please Visit Protospace" +warning, this means the web client can't talk to the API server properly. + +Navigate to [http://127.0.0.1:8000/admin/api/member/1/change/](http://127.0.0.1:8000/admin/api/member/1/change/) and log in with the +super user credentials you created during the API server setup. + +Scroll down and check "Is staff" and click today by "Vetted date". + +Scroll to the bottom and click "Save". + +Go back and refresh Spaceport. You should now be Staff, which grants you the +same powers as a director. Navigate to [http://127.0.0.1:3000/admin](http://127.0.0.1:3000/admin) to confirm. + +## Running Cron Jobs + +Spaceport runs commands periodically to manage infomation that changes with +time and generate the stats. Running them is optional and you can run them +manually like so: + +``` +$ source env/bin/activate +(env) $ DEBUG=true python manage.py run_minutely +(env) $ DEBUG=true python manage.py run_hourly +(env) $ DEBUG=true python manage.py run_daily +``` + +Or automatically: + +``` +$ crontab -e +``` + +Add to the bottom of the file: + +``` +10 10 * * * /whatever/spaceport/apiserver/env/bin/python /whatever/spaceport/apiserver/manage.py run_daily +58 * * * * /whatever/spaceport/apiserver/env/bin/python /whatever/spaceport/apiserver/manage.py run_hourly +* * * * * /whatever/spaceport/apiserver/env/bin/python /whatever/spaceport/apiserver/manage.py run_minutely +``` + +Replace `whatever` with the path to Spaceport. diff --git a/apiserver/docs/source/dev_webclient.md b/apiserver/docs/source/dev_webclient.md new file mode 100644 index 0000000..822149f --- /dev/null +++ b/apiserver/docs/source/dev_webclient.md @@ -0,0 +1,39 @@ +# Web Client Development Setup + +This guide assumes you are using Debian GNU/Linux 11 or Ubuntu 20.04 LTS. If you +aren't, just spin up a VM with the correct version. Things break if you don't. + +## Install Dependencies + +``` +$ sudo apt update +$ sudo apt install nodejs npm +$ sudo npm install --global yarn +``` + +Clone the repo. Skip this step if you already have it: + +``` +$ git clone https://github.com/Protospace/spaceport.git +``` + +Set up nodejs: + +``` +$ cd spaceport/webclient/ +$ yarn install +``` + +## Running + +Run the development server: + +``` +$ HOST=0.0.0.0 yarn start +``` + +You'll see about 500 warnings which you can safely ignore or help get rid of. + +The development server is now listening on port 3000. You can connect to it by +opening `http://:3000/` in your web browser. If it's running +locally, that would be [http://127.0.0.1:3000/](http://127.0.0.1:3000/). diff --git a/apiserver/docs/source/index.rst b/apiserver/docs/source/index.rst index 9fbfad6..36c3c2a 100644 --- a/apiserver/docs/source/index.rst +++ b/apiserver/docs/source/index.rst @@ -11,7 +11,8 @@ Spaceport Documentation :caption: Contents: dev - apioverview api ldap dev_apiserver + dev_webclient + dev_running