Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

update README for release 1.2.20. #77

Merged
merged 1 commit into from
Oct 8, 2024
+50 −25
Merged

update README for release 1.2.20. #77

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
### 1.2.20 release 2024-10-08

- Add Telegram notifications

### 1.2.19 release 2024-09-02

- Let user define the request timeout
Expand Down
71 changes: 46 additions & 25 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,10 @@ $ docker run --rm -v ./soba-backups:/backups -e GITHUB_TOKEN=<token-here> -e GIT

## latest updates

### 1.2.20 release 2024-10-08

- Add Telegram notifications

### 1.2.19 release 2024-09-02

- Let user define the request timeout
Expand Down Expand Up @@ -136,7 +140,7 @@ For instructions on how to run soba on Kubernetes, see [here](kubernetes/README.

## scheduling backups

Backups can be scheduled to run by setting an additional environment variable: `GIT_BACKUP_INTERVAL`. The value is the can be specified in hours (default) or minutes. For example, this will run the backup daily:
Backups can be scheduled to run by setting an additional environment variable: `GIT_BACKUP_INTERVAL`. The value can be specified in hours (default) or minutes. For example, this will run the backup daily:

```bash
export GIT_BACKUP_INTERVAL=24h
Expand All @@ -149,8 +153,8 @@ export GIT_BACKUP_INTERVAL=45m
```

note:
- if you don't specify the trailing 'm' or 'h' then hours are assumed.
- the interval is added to the start of the last backup and not the time it finished, therefore ensure the interval is greater than the duration of a backup.
- if you don't specify the trailing 'm' or 'h' then hours are assumed.
- the interval is added to the start of the last backup and not the time it finished, therefore ensure the interval is greater than the duration of a backup.

## rotating backups

Expand All @@ -171,8 +175,25 @@ export GIT_REQUEST_TIMEOUT=600

## notifications

### Telegram
*(since release 1.2.20)*
To send a Telegram message on completion, set the environment variables:
`SOBA_TELEGRAM_BOT_TOKEN` with the bot token
`SOBA_TELEGRAM_CHAT_ID` with the chat/group id

To get the bot token:
- send a message to @BotFather of /newbot
- submit a name, e.g. soba-notifier
- submit a username for the bot
- record bot token

To get the chat id:
- add the bot user to the group (get group info and click Add)
- run command:`curl -s -X POST https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates`
- record the chat id in the response

### Slack
*(since release 1.2.16)*
*(since release 1.2.16)*
To send a Slack message on completion, set the environment variables:
`SLACK_CHANNEL_ID` with the channel id
`SLACK_API_TOKEN` with the token for the Slack app
Expand All @@ -181,28 +202,28 @@ For example:
`$ export SLACK_API_TOKEN=xoxb-***********-************-************************`

#### note
- channel id can be in `About` section at bottom of the channel details
- the app needs to be added under `Apps` in the `Integrations` section of channel details
- use the token starting with `xoxb-` and not the one starting with `xoxp-`
- channel id can be in `About` section at bottom of the channel details
- the app needs to be added under `Apps` in the `Integrations` section of channel details
- use the token starting with `xoxb-` and not the one starting with `xoxp-`

### webhooks
*(since release 1.2.8)*
*(since release 1.2.8)*
To send a webhook on completion of a run: set the environment variable `SOBA_WEBHOOK_URL` with the url of the endpoint.
For example:
`$ export SOBA_WEBHOOK_URL=https://api.example.com/webhook`
`$ export SOBA_WEBHOOK_URL=https://api.example.com/webhook`

#### webhook payload
The payload is a JSON document containing details of the backup run. The default format lists each repository and the success or failure of its backup. You can see an example [here](examples/webhook.json).
For a shorter format, with just stats on the success and failure counts, use the environment variable `SOBA_WEBHOOK_FORMAT`.
For example:
`$ export SOBA_WEBHOOK_FORMAT=short`
You can see a sample [here](examples/webhook-short.json).
*The default format (if not specified) is `long`*
You can see a sample [here](examples/webhook-short.json).
*The default format (if not specified) is `long`*

> NOTE: The long format webhook will contain a list of your repos and, if there's an error, may contain other details including URLs. Please keep this in mind when sending to endpoints that may be insecure.

### ntfy
*(since release 1.2.10)*
*(since release 1.2.10)*
ntfy is a popular service that enables push notifications for desktop and mobile apps.
To send a message on completion of a run: set the environment variable `SOBA_NTFY_URL` with the url of the endpoint.
For example:
Expand All @@ -212,25 +233,25 @@ For example:

### persistence

Messages are written to stdout and can be persisted by directing to a file, e.g.
Messages are written to stdout and can be persisted by directing to a file, e.g.
`soba > soba.log`

#### logging to /var/log/soba

create a user called soba:
`sudo adduser soba`
create a log directory:
`sudo mkdir /var/log/soba`
set user permissions:
`sudo chown soba /var/log/soba && sudo chmod 700 /var/log/soba`
switch to soba user:
`sudo su - soba`
run soba and direct output:
`soba > /var/log/soba/soba.log`
create a user called soba:
`sudo adduser soba`
create a log directory:
`sudo mkdir /var/log/soba`
set user permissions:
`sudo chown soba /var/log/soba && sudo chmod 700 /var/log/soba`
switch to soba user:
`sudo su - soba`
run soba and direct output:
`soba > /var/log/soba/soba.log`

### rotation

[Logrotate](https://linux.die.net/man/8/logrotate) is a utility that comes with most Linux distributions and removes and/or compresses messages older than a certain number of hours or days.
[Logrotate](https://linux.die.net/man/8/logrotate) is a utility that comes with most Linux distributions and removes and/or compresses messages older than a certain number of hours or days.
This example assumes you persist the log file to /var/log/soba/soba.log
create a file in /etc/logrotate.d/soba with the following content:

Expand Down Expand Up @@ -265,7 +286,7 @@ ensure the user running soba has an entry in `/etc/cron.allow`.

run `crontab -e`

add the following (assuming you have a user called soba with a script to run it called backup in their home directory):
add the following (assuming you have a user called soba with a script to run it called backup in their home directory):
`* * * * * /usr/bin/flock -n /tmp/soba.lockfile /home/soba/backup >> /var/log/soba/soba.log 2>&1`

note: A useful tool for testing cron jobs is [crontab guru](https://crontab.guru/).
Expand Down
Loading