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
|
||||
- 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*.
|
||||
|
|
|
|||
Loading…
Reference in a new issue