From 6b5ccc2be6a2fd1048aa7268f809b19741bf44bc Mon Sep 17 00:00:00 2001 From: jedi Date: Mon, 23 Oct 2023 17:08:26 +0200 Subject: [PATCH] restructure docs --- README.md | 43 ++++++++++++++++-- docs/deployment.md | 102 ++++++++++++++++++++++++++++++++++++++++++ docs/development.md | 105 ++++++++++++++++++++++++++++++++++++++++++++ docs/federation.md | 23 ++++++++++ docs/index.md | 45 ++----------------- 5 files changed, 272 insertions(+), 46 deletions(-) create mode 100644 docs/deployment.md create mode 100644 docs/development.md create mode 100644 docs/federation.md diff --git a/README.md b/README.md index a2c0135..7f91e3e 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # toolshed -## Installation / Development +## Development ``` bash git clone https://github.com/gr4yj3d1/toolshed.git @@ -12,7 +12,10 @@ or git clone https://git.neulandlabor.de/j3d1/toolshed.git ``` -### Backend +all following development mode commands support auto-reloading and hot-reloading where applicable, they do not need to bw +restarted after changes. + +### Backend only ``` bash cd toolshed/backend @@ -26,7 +29,7 @@ python manage.py runserver 0.0.0.0:8000 --insecure to run this in properly in production, you need to configure a webserver to serve the static files and proxy the requests to the backend, then run the backend with just `python manage.py runserver` without the `--insecure` flag. -### Frontend +### Frontend only ``` bash cd toolshed/frontend @@ -34,13 +37,45 @@ npm install npm run dev ``` -### Docs +### Docs only ``` bash cd toolshed/docs mkdocs serve ``` +### Full stack + +``` bash +cd toolshed +docker-compose -f deploy/docker-compose.override.yml up --build +``` + +## Deployment + +### Requirements + +- python3 +- python3-pip +- python3-venv +- wget +- unzip +- nginx +- uwsgi + +### Installation + +* Get the latest release from +`https://git.neulandlabor.de/j3d1/toolshed/releases/download//toolshed.zip` or +`https://github.com/gr4yj3d1/toolshed/archive/refs/tags/.zip`. +* Unpack it to `/var/www` or wherever you want to install toolshed. +* Create a virtual environment and install the requirements. +* Then run the configuration script. +* Configure your webserver to serve the static files and proxy the requests to the backend. +* Configure your webserver to run the backend with uwsgi. + +for detailed instructions see [docs](/docs/deployment.md). + ## CLI Client ### Requirements diff --git a/docs/deployment.md b/docs/deployment.md new file mode 100644 index 0000000..9262ebe --- /dev/null +++ b/docs/deployment.md @@ -0,0 +1,102 @@ +# Deployment + +## Native + +### Requirements + +- python3 +- python3-pip +- python3-venv +- wget +- unzip +- nginx +- uwsgi +- certbot + +### Installation + +Get the latest release: + +``` bash +cd /var/www # or wherever you want to install toolshed +wget https://git.neulandlabor.de/j3d1/toolshed/releases/download//toolshed.zip +``` +or from github: +``` bash +cd /var/www # or wherever you want to install toolshed +wget https://github.com/gr4yj3d1/toolshed/archive/refs/tags/.zip -O toolshed.zip +``` + +Extract and configure the backend: + +``` bash +unzip toolshed.zip +cd toolshed/backend +python3 -m venv venv +source venv/bin/activate +pip install -r requirements.txt +python configure.py +``` + +Configure uWSGI to serve the backend locally: + +``` bash +cd /var/www/toolshed/backend +cp toolshed.ini /etc/uwsgi/apps-available/ +ln -s /etc/uwsgi/apps-available/toolshed.ini /etc/uwsgi/apps-enabled/ +systemctl restart uwsgi +``` + +Configure nginx to serve the static files and proxy the requests to the backend: + +``` bash +cd /var/www/toolshed/backend +cp toolshed.nginx /etc/nginx/sites-available/toolshed +ln -s /etc/nginx/sites-available/toolsheed /etc/nginx/sites-enabled/ +systemctl restart nginx +``` + +Configure certbot to get a certificate for the domain: + +``` bash +certbot --nginx -d +``` + +### Update + +``` bash +cd /var/www +wget https://git.neulandlabor.de/j3d1/toolshed/releases/download//toolshed.zip +unzip toolshed.zip +cd toolshed/backend +source venv/bin/activate +pip install -r requirements.txt +python configure.py +systemctl restart uwsgi +``` + +## Docker + +### Requirements + +- docker +- docker-compose +- git + +### Installation + +``` bash +git clone https://git.neulandlabor.de/j3d1/toolshed.git +# or +git clone https://github.com/gr4yj3d1/toolshed.git +cd toolshed +docker-compose -f deploy/docker-compose.prod.yml up -d --build +``` + +### Update + +``` bash +toolshed +git pull +docker-compose -f deploy/docker-compose.prod.yml up -d --build +``` \ No newline at end of file diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 0000000..3fcd229 --- /dev/null +++ b/docs/development.md @@ -0,0 +1,105 @@ +# Development + +``` bash +git clone https://github.com/gr4yj3d1/toolshed.git +``` + +or + +``` bash +git clone https://git.neulandlabor.de/j3d1/toolshed.git +``` + +## Native + +To a certain extent, the frontend and backend can be developed independently. The frontend is a Vue.js project and the +backend is a DRF (Django-Rest-Framework) project. If you want to develop the frontend, you can do so without the backend +and vice +versa. However, especially for the frontend, it is recommended to use the backend as well, as the frontend does not have +a lot of 'offline' functionality. +If you want to run the fullstack application, it is recommended to use the [docker-compose](#docker) method. + +### Frontend + +install `node.js` and `npm` + +on Debian* for example: `sudo apt install npm` + +``` bash +cd toolshed/frontend +npm install +npm run dev +``` + +### Backend + +Install `python3`, `pip` and `virtualenv` + +on Debian* for example: `sudo apt install python3 python3-pip python3-venv` + +Prepare backend environment + +``` bash +cd toolshed/backend +python -m venv venv +source venv/bin/activate +pip install -r requirements.txt +``` + +Run the test suite: + +``` bash +python manage.py test +``` + +optionally with coverage: + +``` bash +coverage run manage.py test +coverage report +``` + +Start the backend in development mode: + +``` bash +python manage.py migrate +cp .env.dist .env +echo "DEBUG = True" >> .env +python manage.py runserver 0.0.0.0:8000 +``` + +provides the api docs at `http://localhost:8000/docs/` + +### Docs (Wiki) + +Install `mkdocs` + +on Debian* for example: `sudo apt install mkdocs` + +Start the docs server: + +``` bash +cd toolshed/docs +mkdocs serve -a 0.0.0.0:8080 +``` + +## Docker + +### Fullstack + +Install `docker` and `docker-compose` + +on Debian* for example: `sudo apt install docker.io docker-compose` + +Start the fullstack application: + +``` bash +docker-compose -f deploy/docker-compose.override.yml up --build +``` + +This will start an instance of the frontend and wiki, a limited DoH (DNS over HTTPS) server and **two** instances of the backend. +The two backend instances are set up to use the domains `a.localhost` and `b.localhost`, the local DoH +server is used to direct the frontend to the correct backend instance. +The frontend is configured to act as if it was served from the domain `a.localhost`. +Access the frontend at `http://localhost:8080/`, backend at `http://localhost:8080/api/`, api docs +at `http://localhost:8080/docs/` and the wiki at `http://localhost:8080/wiki/`. \ No newline at end of file diff --git a/docs/federation.md b/docs/federation.md new file mode 100644 index 0000000..d242677 --- /dev/null +++ b/docs/federation.md @@ -0,0 +1,23 @@ +# Federation + +This section will cover how federation works in Toolshed. + +## What is Federation? + +Since user of Toolshed you can search and interact the inventory of all their 'friends' that are potentially on +different servers there is a need for a way to communicate between servers. We don't want to rely on a central server that +stores all the data and we don't want to have a central server that handles all the communication between servers. This +is where federation comes in. Toolshed uses a protocol that can not only exchange data with the server where the user +is registered but also with the servers where their friends are registered. + +## How does it work? + +Any user can register on any server and creates a personal key pair. The public key is stored on the server and the private +key is stored on the client. The private key is used to sign all requests to the server and the public key is used to +verify the signature. Once a user has registered on a server they can send friend requests to other users containing +their public key. If the other user accepts the friend request, the server stores the public key of the friend and +uses it to verify access to the friend's inventory. While accepting a friend request the user also automatically sends +their own public key to the friend's server. This way both users can access each other's inventory. + +The protocol is based on a simple HTTPS API exchanging JSON data that is signed with the user's private key. By default +Toolshed servers provide a documentation of the API at [/docs/api](/docs/api). \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 0ba4a97..95588dd 100644 --- a/docs/index.md +++ b/docs/index.md @@ -6,47 +6,8 @@ This is the documentation for the Toolshed project. It is a work in progress. `#social` `#network` `#federation` `#decentralized` `#federated` `#socialnetwork` `#fediverse` `#community` `#hashtags` ## Getting Started + - [Deploying Toolshed](deployment.md) + - [Development Setup](development.md) + - [About Federation](federation.md) -## Installation -``` bash - # TODO add installation instructions - # similar to development instructions just with more docker - # TODO add docker-compose.yml -``` - -## Development - -``` bash -git clone https://github.com/gr4yj3d1/toolshed.git -``` -or -``` bash -git clone https://git.neulandlabor.de/j3d1/toolshed.git -``` - -### Frontend - -``` bash -cd toolshed/frontend -npm install -npm run dev -``` - -### Backend - -``` bash -cd toolshed/backend -python3 -m venv venv -source venv/bin/activate -pip install -r requirements.txt -python manage.py migrate -python manage.py runserver 0.0.0.0:8000 -``` - -### Docs - -``` bash -cd toolshed/docs -mkdocs serve -a 0.0.0.0:8080 -```