tanner/spaceport
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Add markdown development docs

Browse Source
This commit is contained in:
Tanner Collin 2022-04-06 23:32:24 +00:00
parent 332b001533
commit 1fb93238c5
5 changed files with 107 additions and 197 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

191
apiserver/docs/source/dev.rst
View File

@ -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.

17
apiserver/docs/source/dev_apiserver.md
View File

@ -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://<ip address>: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/).

54
apiserver/docs/source/dev_running.md Normal file
View File

@ -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.

39
apiserver/docs/source/dev_webclient.md Normal file
View File

@ -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://<ip address>: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/).

3
apiserver/docs/source/index.rst
View File

@ -11,7 +11,8 @@ Spaceport Documentation
:caption: Contents:
dev
apioverview
api
ldap
dev_apiserver
dev_webclient
dev_running