restructure docs

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/<version>/toolshed.zip` or 
+`https://github.com/gr4yj3d1/toolshed/archive/refs/tags/<version>.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

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/<version>/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/<version>.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 <domain>
+```
+
+### Update
+
+``` bash
+cd /var/www
+wget https://git.neulandlabor.de/j3d1/toolshed/releases/download/<version>/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
+```

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/`.

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

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
-```