j3d1/toolshed
1
0
Fork 0
Code Issues 9 Pull requests 1 Projects Releases Packages Wiki Activity

restructure docs
All checks were successful
continuous-integration/drone/push Build is passing
Details

Browse source
This commit is contained in:
j3d1 2023-10-23 17:08:26 +02:00
parent bbc2faeb7b
commit 6b5ccc2be6
5 changed files with 272 additions and 46 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

43
README.md
View file

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

102
docs/deployment.md Normal file
View file

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

105
docs/development.md Normal file
View file

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

23
docs/federation.md Normal file
View file

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

45
docs/index.md
View file

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