forked from uncloud/uncloud
[doc] Move install and co. into the main documentation
This commit is contained in:
Nico Schottelius
parent
a091079677
commit
9d5d8657cb
2 changed files with 91 additions and 140 deletions
135
doc/README.md
135
doc/README.md
|
|
@ -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/<uuid> should list uuids of disks
|
|
||||||
* UPDATE on ../vm/disk/<uuid> with size=newsize
|
|
||||||
* Newsize > oldsize!
|
|
||||||
* Triggers shutdown of VM
|
|
||||||
* Resizes disk
|
|
||||||
* Starts VM
|
|
||||||
* Maybe confirm flag?
|
|
||||||
|
|
||||||
|
|
||||||
### Adding a disk to a VM
|
|
||||||
|
|
||||||
(TBD)
|
|
||||||
|
|
@ -1,9 +1,64 @@
|
||||||
* Bootstrap
|
* Bootstrap / Installation
|
||||||
- Login via a user so that the user object gets created
|
** Pre-requisites by operating system
|
||||||
- Run the following (replace nicocustomer with the username)
|
*** Alpine
|
||||||
#+BEGIN_SRC sh
|
#+BEGIN_SRC sh
|
||||||
python manage.py bootstrap-user --username nicocustomer
|
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
|
#+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
|
* Testing / CLI Access
|
||||||
Access via the commandline (CLI) can be done using curl or
|
Access via the commandline (CLI) can be done using curl or
|
||||||
|
|
@ -16,6 +71,33 @@
|
||||||
#+BEGIN_SRC sh
|
#+BEGIN_SRC sh
|
||||||
http --auth nicocustomer:$(pass ldap/nicocustomer) localhost:8000/api/
|
http --auth nicocustomer:$(pass ldap/nicocustomer) localhost:8000/api/
|
||||||
#+END_SRC
|
#+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
|
* Database
|
||||||
** uncloud clients access the data base from a variety of outside hosts
|
** uncloud clients access the data base from a variety of outside hosts
|
||||||
** So the postgresql data base needs to be remotely accessible
|
** So the postgresql data base needs to be remotely accessible
|
||||||
|
|
@ -127,3 +209,7 @@
|
||||||
|
|
||||||
*** Decision
|
*** Decision
|
||||||
We use integers, because they are easy.
|
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*.
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue