Backupbot Specification #258
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: toolshed/docs.coopcloud.tech#258
Loading…
x
Reference in New Issue
Block a user
No description provided.
Delete Branch "p4u1/docs.coopcloud.tech:backupbottwo-spec"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
For coop-cloud/organising#594
This is an initial draft for the backupbot-two specification. Note that this is the first time, that I tried to write a somewhat formal description on how something should work :D
Also note, that this does not reflect what is implemented, but what we want, as discussed in the following issues and meeting:
TODO:
specification
For Maintainers
For Operators
check when
sh -c 'command'is necessarydecide where files should go
Open Questions
@3wordchant @nicksellen @moritz @yksflip (am I forgetting anyone?) as
backup-bot-twohackers, your input would be great!Incredible work @p4u1! Thanks for diving into it 🤯
One bikeshed, on the dreaded naming topic: should we pick a name for it now we're going "official" with a spec?
backup-bot-twocould be something more generalised? This also might make sense in the context of how general this sepc is written in, referring to stacks/docker/etc. and not Co-op Cloud specifics. The labels are very Co-op Cloud specific. Alsobackupbotvs.backup-bot-two. No strong feelings but feels like maybe the time to bring it up...For hooks, I know
borgmatichas specific hooks for error scenarios: https://torsion.org/borgmatic/docs/how-to/add-preparation-and-cleanup-steps-to-backups/#error-hooks 🤔Unsure what "should abra implement backup and restore or only provide an integration?" means? What we have now is that
abraimplements adocker exec-based "pass args" approach to triggerbackup-bot-twoon demand... maybe that should be documented also? E.g.004cd70aed/cli/app/backup.go (L153)I think I followed coop-cloud/backup-bot-two#20 (comment)@ -0,0 +6,4 @@## RequirementsThe key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this specification are to be interpreted as described in [RFC-2119].[RFC-2119]missing link?@ -0,0 +45,4 @@**Type:** boolean**Default:** false**Description:**Enables backupbot for this compose stack. The labe should be added to the main service of the compose stack.%s/labe/label%s/backupbot/backup-bot-twoDid
%s/backupbot/backupsto keep it genericThanks for the feedback! Note that I'm still working on the docs for maintainers and operators, but feedback on the spec part is very appreciated :)
I'm all in for a different name, but not so creative atm.
"should abra implement backup and restore or only provide an integration?" means, that before
575f9905f1it was possible to create a backup or do a restore usingabrawithout having abackupbot-twodeployed which could be nice for testing purposes and maybe other use casesLooks fantastic, amazing work @p4u1 👏
@ -0,0 +8,4 @@The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this specification are to be interpreted as described in [RFC-2119].When backing up a docker stack you MUST first check if the `backupbot.backup`. It MUST be set to true, for the backup to happen.Maybe remove this, seems the same as line 15 "To enable backups"
@ -0,0 +12,4 @@## BackupTo enable backups for a docker stack, the `backupbot.backup=true` label MUST be on any of its services. It SHOULD be declared on the first service.Is the behaviour defined if one service sets
backupbot.backup=trueand another sets it tobackupbot.backup=false?@ -0,0 +16,4 @@### Volumes and pathsBy default all volumes MUST be backed up. A volume MAY be excluded from the backup when `backupbot.backup.volumes.{volume_name}=false` is set, where `{volume_name}` is the name of the volume.So the spec allows backing up a volume even if
...{volume_name}=false? Is there any harm in changing this to "MUST"?Changed it to "MUST"
@ -0,0 +69,4 @@**Type:** string**Default:** ""**Description:**A comma seperated list of paths. When one or more paths are set, it only backups up those on the given volume instead of the whole volume.seperated -> separated
backups up -> backs up
@ -0,0 +95,4 @@**Type:** string**Default:** ""**Description:**A command, that gets executed after the files are backuped.backuped -> backed up
I like how self explanatory
backup-botis. @decentral1se if you're down to fully retirebackup-botwe could maybe drop the-two.If we wanted a more bRaNdEd name, how about:
chancey(following "definitely not Pokémon" tool naming convention, something something takes care of eggs, heals things)guarda(following "spanish imperative" accidental tool naming convention, means "save!", unfortunately a name collision with a crypto wallet tho)pocus(following "magic words" abra naming convention)@ -0,0 +24,4 @@### OutputA backup implementation SHOULD provide the backup of one or multiple stacks in a `.tar.gz` format. In that case each volume MUST be in `/var/lib/docker/volumes/{volume_name}`, where `{volume_name}` is the name of each volume that got backed up.I think
{volume_name}can be confusing in this case. Because inbackupbot.backup.volumes.{volume_name}.paththe{volume_name}would be for exampleassets, while in the path/var/lib/docker/volumes/{volume_name}it would beappname_example_com_assets.Maybe writing
/var/lib/docker/volumes/{stack_name}_{volume_name}would clearer.Thank you @p4u1 great work 🚀
Great work, just had another read. Just to update: I think coop-cloud/docs.coopcloud.tech#258 (comment) needs to triaged and then we coud merge this. In order to write the tutorial and so on, we need to finish the implementation in abra, right? See coop-cloud/backup-bot-two#42 for more.
EDIT: oops, just saw the open questions... do we need to orga a tech meeting to thrash out some details finally?
@ -0,0 +19,4 @@### `abra``abra` will read labels and store backups in `~/.abra/backups/...` .It also provides an integration for `backup-bot-two`.Thought: do we also need to spec out the interface?
coop-cloud/backup-bot-two#53 got me thinking about this.
@ -0,0 +79,4 @@**Example 2:**```backupbot.backup.volumes.{volume_name}.path: '/var/lib/myapp/foo,/var/lib/myapp/bar'Writing in this example and the one above absolute paths can be confusing.
This draft is now implemented. How about to merge and close this and open issues for the open questions?
@p4u1 if you don't have time, i can merge this in as per coop-cloud/docs.coopcloud.tech#258 (comment)?
Yes, please merge :)
WIP: Backupbot Specificationto Backupbot Specificationdecentral1se referenced this pull request from toolshed/abra2024-10-29 11:01:51 +00:00
Are the files on the right place? I can't find these docs online.
Coming up:
782771f440I have a standing TODO to patch those docs with fixes after I get further on coop-cloud/abra#447 but all help is welcome!