From 9d5d8657cb407a6fa4a2dc69736526ca04388e28 Mon Sep 17 00:00:00 2001 From: Nico Schottelius Date: Sat, 1 Aug 2020 23:42:36 +0200 Subject: [PATCH] [doc] Move install and co. into the main documentation --- doc/README.md | 135 ------------------------------ doc/uncloud-manual-2020-08-01.org | 96 +++++++++++++++++++-- 2 files changed, 91 insertions(+), 140 deletions(-) delete mode 100644 doc/README.md diff --git a/doc/README.md b/doc/README.md deleted file mode 100644 index 3bded7e..0000000 --- a/doc/README.md +++ /dev/null @@ -1,135 +0,0 @@ -## Install - -### OS package requirements - -Alpine: - -``` -apk add openldap-dev postgresql-dev -``` - -Debian/Devuan: - -``` -apt install postgresql-server-dev-all -``` - - -### Python requirements - -If you prefer using a venv, use: - -``` -python -m venv venv -. ./venv/bin/activate -``` - -Then install the requirements - -``` -pip install -r requirements.txt -``` - -### Database requirements - -Due to the use of the JSONField, postgresql is required. - -First create a role to be used: - -``` -postgres=# create role nico login; -``` - -Then create the database owner by the new role: - -``` -postgres=# create database uncloud owner nico; -``` - -Installing the postgresql service is os dependent, but some hints: - -* Alpine: `apk add postgresql-server && rc-update add postgresql && rc-service postgresql start` -* Debian/Devuan: `apt install postgresql` - -After postresql is started, apply the migrations: - -``` -python manage.py migrate -``` - -## Flows / Orders - - -### Creating a VMHost - -### Creating a VM - -* Create a VMHost -* Create a VM on a VMHost - - -### Creating a VM Snapshot - - -## Working Beta APIs - -These APIs can be used for internal testing. - -### URL Overview - -``` -http -a nicoschottelius:$(pass ungleich.ch/nico.schottelius@ungleich.ch) http://localhost:8000 -``` - -### Snapshotting - -``` -http -a nicoschottelius:$(pass ungleich.ch/nico.schottelius@ungleich.ch) http://localhost:8000/vm/snapshot/ vm_uuid=$(uuidgen) -``` - -## VPNs - -VPNs consist of VPNPools ("networks of networks") which are handled by -VPNHosts. Users can requests VPNs with specific sizes. - -VPNs support both IPv6 and IPv4. However only IPv6 support has not been - -### Managing VPNPools - -``` -http -a nico:$(pass ldap/nico) https://uncloud.place7.ungleich.ch/v1/admin/vpnpool/ network=2a0a:e5c1:200:: network_size=40 subnetwork_size=48 vpn_hostname=vpn-2a0ae5c1200.ungleich.ch wireguard_private_key=$(wg genkey) -``` - -This will create the VPNPool 2a0a:e5c1:200::/40 from which /48 -networks will be used for clients. - -VPNPools can only be managed by staff. - -### Managing VPNNetworks - - -To request a network as a client, use the following call: - -``` -http -a nicoschottelius:$(pass ungleich.ch/nico.schottelius@ungleich.ch)https://uncloud.place7.ungleich.ch/v1/net/vpn/ network_size=48 wireguard_public_key=$(wg genkey | tee privatekey | wg pubkey) -``` - -VPNNetworks can be managed by all authenticated users. - - -## Proposed (uncoded) flows - -### Changing the disk size of a VM - -* GET on ../vm/vm/ should list uuids of disks -* UPDATE on ../vm/disk/ with size=newsize - * Newsize > oldsize! -* Triggers shutdown of VM -* Resizes disk -* Starts VM -* Maybe confirm flag? - - -### Adding a disk to a VM - -(TBD) diff --git a/doc/uncloud-manual-2020-08-01.org b/doc/uncloud-manual-2020-08-01.org index 4a61407..f98e8b3 100644 --- a/doc/uncloud-manual-2020-08-01.org +++ b/doc/uncloud-manual-2020-08-01.org @@ -1,9 +1,64 @@ -* Bootstrap - - Login via a user so that the user object gets created - - Run the following (replace nicocustomer with the username) - #+BEGIN_SRC sh - python manage.py bootstrap-user --username nicocustomer +* Bootstrap / Installation +** Pre-requisites by operating system +*** Alpine + #+BEGIN_SRC sh +apk add openldap-dev postgresql-dev +#+END_SRC +*** Debian/Devuan: + #+BEGIN_SRC sh +apt install postgresql-server-dev-all +#+END_SRC +** Creating a virtual environment / installing python requirements +*** Virtual env + To separate uncloud requirements, you can use a python virtual + env as follows: + #+BEGIN_SRC sh +python3 -m venv venv +. ./venv/bin/activate +#+END_SRC + Then install the requirements + #+BEGIN_SRC sh +pip install -r requirements.txt +#+END_SRC +** Setting up the the database +*** Install the database service + The database can run on the same host as uncloud, but can also run + a different server. Consult the usual postgresql documentation for + a secure configuration. +**** Alpine + #+BEGIN_SRC sh +apk add postgresql-server +rc-update add postgresql +rc-service postgresql start` +#+END_SRC + +**** Debian/Devuan: + #+BEGIN_SRC sh + apt install postgresql #+END_SRC +*** Create the database + Due to the use of the JSONField, postgresql is required. + To get started, + create a database and have it owned by the user that runs uncloud + (usually "uncloud"): + + #+BEGIN_SRC sh +bridge:~# su - postgres +bridge:~$ psql +postgres=# create role uncloud login; +postgres=# create database uncloud owner nico; +#+END_SRC +*** Creating the schema + #+BEGIN_SRC sh +python manage.py migrate +#+END_SRC + +** Bootstrap + - Login via a user so that the user object gets created + - Run the following (replace nicocustomer with the username) + #+BEGIN_SRC sh + python manage.py bootstrap-user --username nicocustomer + #+END_SRC * Testing / CLI Access Access via the commandline (CLI) can be done using curl or @@ -16,6 +71,33 @@ #+BEGIN_SRC sh http --auth nicocustomer:$(pass ldap/nicocustomer) localhost:8000/api/ #+END_SRC +* Using uncloud products +** VPN +*** Creating a VPN pool + + #+BEGIN_SRC sh +http -a uncloudadmin:$(pass uncloudadmin) https://localhost:8000/v1/admin/vpnpool/ \ + network=2a0a:e5c1:200:: network_size=40 subnetwork_size=48 \ + vpn_hostname=vpn-2a0ae5c1200.ungleich.ch wireguard_private_key=$(wg genkey) + #+END_SRC + +This will create the VPNPool 2a0a:e5c1:200::/40 from which /48 +networks will be used for clients. + +VPNPools can only be managed by staff. + +*** Managing VPNNetworks + +To request a network as a client, use the following call: + + #+BEGIN_SRC sh + http -a user:$(pass user) https://localhost:8000/v1/net/vpn/ \ + network_size=48 \ + wireguard_public_key=$(wg genkey | tee privatekey | wg pubkey) +``` + +VPNNetworks can be managed by all authenticated users. + * Database ** uncloud clients access the data base from a variety of outside hosts ** So the postgresql data base needs to be remotely accessible @@ -127,3 +209,7 @@ *** Decision We use integers, because they are easy. + +** Documentation + This documentation is written in org-mode. To compile it to + html/pdf, just open emacs and press *C-c C-e l p*.