Merge lp:~fo0bar/turku/turku-api-doc into lp:turku/turku-api

Proposed by Ryan Finnie
Status: Merged
Approved by: Tom Haddon
Approved revision: 61
Merged at revision: 61
Proposed branch: lp:~fo0bar/turku/turku-api-doc
Merge into: lp:turku/turku-api
Diff against target: 86 lines (+81/-0)
1 file modified
README.md (+81/-0)
To merge this branch: bzr merge lp:~fo0bar/turku/turku-api-doc
Reviewer Review Type Date Requested Status
Tom Haddon Approve
Review via email: mp+381209@code.launchpad.net

Commit message

Add README.md

To post a comment you must log in.
Revision history for this message
Canonical IS Mergebot (canonical-is-mergebot) wrote :

This merge proposal is being monitored by mergebot. Change the status to Approved to merge.

Revision history for this message
Tom Haddon (mthaddon) wrote :

LGTM

review: Approve
Revision history for this message
Canonical IS Mergebot (canonical-is-mergebot) wrote :

Change successfully merged at revision 61

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1=== added file 'README.md'
2--- README.md 1970-01-01 00:00:00 +0000
3+++ README.md 2020-03-25 23:09:12 +0000
4@@ -0,0 +1,81 @@
5+# turku-api
6+
7+## About Turku
8+Turku is an agent-based backup system where the server doing the backups has no direct access to the machine being backed up. Instead, the machine's agent coordinates with an API server and opens a reverse tunnel to the storage server when it is time to do a backup.
9+
10+Turku is comprised of the following components:
11+
12+* [turku-api](https://launchpad.net/turku/turku-api), a Django web application which acts as an API server and coordinator.
13+* [turku-storage](https://launchpad.net/turku/turku-storage), an agent installed on the servers which do the actual backups.
14+* [turku-agent](https://launchpad.net/turku/turku-agent), an agent installed on the machines to be backed up.
15+
16+turku-api has the following models:
17+
18+* Auth, registration secrets for Machines and Storages.
19+* Storage, registered agents for servers running turku-storage.
20+* Machine, registered agents for machines running turku-agent.
21+* Source, sources of data to be backed up on a Machine.
22+* FilterSet, rsync filter definitions of what to include and exclude (optional).
23+* BackupLog, records of Machine/Source backup runs.
24+
25+## Installation
26+
27+turku-api is a standard Django application; please see [Django's installation guide](https://docs.djangoproject.com/en/1.11/topics/install/) for setting up an application. Django 1.6 (Ubuntu Trusty era) through Django 1.11 (Ubuntu Bionic era) have been tested.
28+
29+turku-api requires Python 3. The following optional Python modules can also be installed:
30+
31+* croniter, for cron-style scheduling definitions
32+
33+It is highly recommended to serve turku-api over HTTPS, as registration and agent-specific secrets are passed from turku-storage and turku-agent agents to turku-api. However, actual backups are done over SSH, not this application.
34+
35+turku-api's default configuration will use a SQLite database. This is fine for small installations, but it's recommended to use a PostgreSQL/MySQL database for larger installations.
36+
37+Besides database configuration, turku-api's default Django settings are adequate. The only recommended change is an installation-specific Django SECRET_KEY. Create ```turku_api/local_settings.py``` with:
38+
39+```
40+SECRET_KEY = 'long random key string'
41+```
42+
43+Any other changes to ```turku_api/settings.py``` should be put in ```turku_api/local_settings.py``` as well.
44+
45+Getting the admin web site working is recommended, but not required.
46+
47+## Configuration
48+
49+Once the installation is complete, you will need to add at least one Storage registration Auth, and at least one Machine registration Auth:
50+
51+```
52+# python3 manage.py shell
53+
54+from django.contrib.auth import hashers
55+from turku_api.models import Auth
56+
57+storage_secret = hashers.get_random_string(30)
58+storage_auth = Auth()
59+storage_auth.active = True
60+storage_auth.name = 'Storages'
61+storage_auth.secret_hash = hashers.make_password(storage_secret)
62+storage_auth.secret_type = 'storage_reg'
63+storage_auth.save()
64+
65+machine_secret = hashers.get_random_string(30)
66+machine_auth = Auth()
67+machine_auth.active = True
68+machine_auth.name = 'Machines'
69+machine_auth.secret_hash = hashers.make_password(machine_secret)
70+machine_auth.secret_type = 'machine_reg'
71+machine_auth.save()
72+
73+print('Storage registration secret is: {}'.format(storage_secret))
74+print('Machine registration secret is: {}'.format(machine_secret))
75+```
76+
77+Multiple of each type of Auth can be created. For example, you may have multiple groups within an organization; creating a separate Machine registration Auth for each group may be desired. turku-api tracks which Auth is used to register a Machine, but the Auth is not used for authentication beyond registration; a Machine-specific generated secret is used for check-ins.
78+
79+## Deployments
80+
81+Once you have the Storage and Machine registration secrets, move on to installing turku-storage and turku-agent agents and registering them with turku-api. See the README.md files in their respective repositories for more details.
82+
83+For small deployments, turku-api, turku-storage, and a turku-agent agent may all be on the same server. For example, the server may have a main turku-api coordinator, a turku-storage agent configured to store backups on a removable USB drive, and a turku-agent agent configured to back up the turku-api SQLite database.
84+
85+For larger deployments, Turku supports scale-out. Load-balancing HTTPS frontends may point to multiple turku-api application servers, which themselves may use primary/secondary PostgreSQL databases. Multiple turku-storage servers may register with turku-api, as storage needs increase. All turku-agent machines will need access to the turku-api application servers (or their frontends) via HTTPS, and to their assigned turku-storage server over SSH. No ingress access is needed to turku-agent machines.
86\ No newline at end of file

Subscribers

People subscribed via source and target branches

to all changes: