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 (+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:

Commit message


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 :


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 ''
2--- 1970-01-01 00:00:00 +0000
3+++ 2020-03-25 23:09:12 +0000
4@@ -0,0 +1,81 @@
5+# turku-api
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.
10+Turku is comprised of the following components:
12+* [turku-api](, a Django web application which acts as an API server and coordinator.
13+* [turku-storage](, an agent installed on the servers which do the actual backups.
14+* [turku-agent](, an agent installed on the machines to be backed up.
16+turku-api has the following models:
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.
25+## Installation
27+turku-api is a standard Django application; please see [Django's installation guide]( for setting up an application. Django 1.6 (Ubuntu Trusty era) through Django 1.11 (Ubuntu Bionic era) have been tested.
29+turku-api requires Python 3. The following optional Python modules can also be installed:
31+* croniter, for cron-style scheduling definitions
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.
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.
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/``` with:
40+SECRET_KEY = 'long random key string'
43+Any other changes to ```turku_api/``` should be put in ```turku_api/``` as well.
45+Getting the admin web site working is recommended, but not required.
47+## Configuration
49+Once the installation is complete, you will need to add at least one Storage registration Auth, and at least one Machine registration Auth:
52+# python3 shell
54+from django.contrib.auth import hashers
55+from turku_api.models import Auth
57+storage_secret = hashers.get_random_string(30)
58+storage_auth = Auth() = True = 'Storages'
61+storage_auth.secret_hash = hashers.make_password(storage_secret)
62+storage_auth.secret_type = 'storage_reg'
65+machine_secret = hashers.get_random_string(30)
66+machine_auth = Auth() = True = 'Machines'
69+machine_auth.secret_hash = hashers.make_password(machine_secret)
70+machine_auth.secret_type = 'machine_reg'
73+print('Storage registration secret is: {}'.format(storage_secret))
74+print('Machine registration secret is: {}'.format(machine_secret))
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.
79+## Deployments
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 files in their respective repositories for more details.
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.
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


People subscribed via source and target branches

to all changes: