Skip to content

Commit

Permalink
formatting and minor corrections
Browse files Browse the repository at this point in the history
  • Loading branch information
@parMaster
parMaster committed Jan 17, 2024
1 parent 5a659ca commit 4f905cb
Show file tree
Hide file tree
Showing 2 changed files with 81 additions and 35 deletions.
93 changes: 64 additions & 29 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -44,52 +44,68 @@ See `config/config_example.yml` for example configuration file, available option
- To build from source, proceed with this manual.

### Foreground mode
*note: this is not recommended for production use, use systemd service instead*
> [!NOTE]
> this is not recommended for production use, use systemd service instead or run it in a Docker container
1. Clone the repository from GitHub

git clone https://github.com/parMaster/zoomrs.git
```sh
git clone https://github.com/parMaster/zoomrs.git
```

2. Make sure `config/config.yml` exists and is configured properly
3. Run `make run` to build the binary and run it in foreground mode

make run
```sh
make run
```
4. To stop the service press `Ctrl+C` (or send `SIGINT`, `SIGTERM` signal to the process)

### Systemd service
1. Repeat steps 1 and 2 from the previous section
2. Run `make deploy` to build the binary and copy everything where it belongs (see `Makefile` for details), enable and run the service

make deploy
```sh
make deploy
```
3. Run `make status` to check the status of the service

make status
```sh
make status
```

Log files are located at `/var/log/zoomrs.log` and `/var/log/zoomrs.err` by default.

### Docker container
1. Clone the repository from GitHub

git clone https://github.com/parMaster/zoomrs.git
```sh
git clone https://github.com/parMaster/zoomrs.git
```

2. Make sure `config/config.yml` exists and is configured properly
3. Check configuration parameters in Dockerfile and docker-compose.yml
4. Build and run container

docker compose up -d
```sh
docker compose up -d
```

## Usage
### Web frontend
Web frontend is available at `http://localhost:8099` by default. You can change the port in the configuration file (`server.listen` parameter).

### Web frontend Pages

#### GET `/`
```http
GET `/`
```
Displays the list of recordings. Each recording has a link to share (view) it. Recordings are sorted by date in descending order. Login is required to view the list. Google OAuth is used for authentication. Access is restricted to users with email addresses from the list specified in the configuration file (see `server.managers`).

Share button is available for each recording, it generates a link to view the recording. Share link looks like:

#### GET `/watch/834d0992ad0d632cf6c3174b975cb5e5?uuid=kzbiTyvQQp2fW6biu8Vy%2BQ%3D%3D`
```http
GET `/watch/834d0992ad0d632cf6c3174b975cb5e5?uuid=kzbiTyvQQp2fW6biu8Vy%2BQ%3D%3D`
```
Displays the page with the meeting title and player to watch the recording. Simple controls besides the embeded player is providing are available.

## API
Expand Down Expand Up @@ -210,17 +226,23 @@ Response when some meetings are not loaded:
Zoomrs comes with a CLI tool to trash/delete recordings from Zoom Cloud. It is useful when running miltiple servers and you want to delete recordings from Zoom Cloud only after all servers have downloaded them. CLI tool is located at `cmd/cli/main.go`. Run `make` to build it and put to `dist/zoomrs-cli`.
It can be run like this:

go run ./cmd/cli --cmd check
```sh
go run ./cmd/cli --cmd check
```

or like this:

./dist/zoomrs-cli --cmd check
```sh
./dist/zoomrs-cli --cmd check
```

Available commands:
- `check` - checks the consistency of the repository: if all recordings are downloaded and if all downloaded recordings are present on the disk, also the size of each recording file is checked. Run this command periodically to make sure everything is OK.
Run it like this:

./dist/zoomrs-cli --cmd check
```sh
./dist/zoomrs-cli --cmd check
```
Example output:
```
2023/06/19 17:15:01 [INFO] starting CheckConsistency
Expand All @@ -229,29 +251,35 @@ Run it like this:
```
- `trash` - trashes recordings from Zoom Cloud. Run it like this:

./zoomrs-cli --dbg --cmd trash --trash 2
```sh
./zoomrs-cli --dbg --cmd trash --trash 2
```

where `2` is 2 days before today, so all the recordings from the bay before yesterday will be trashed. This is designed this way to run it as a cron job every day. Cron job line example:

00 10 * * * cd $HOME/go/src/zoomrs/dist && ./zoomrs-cli --cmd trash --trash 2 --config ../config/config_cli.yml >> /var/log/cron.log 2>&1
```sh
00 10 * * * cd $HOME/go/src/zoomrs/dist && ./zoomrs-cli --cmd trash --trash 2 --config ../config/config_cli.yml >> /var/log/cron.log 2>&1
```

will trash all recordings from the day before yesterday every day at 10:00 AM. `--config` option is used to specify the path to the configuration file. `--dbg` option can be used to enable debug logging. Logs are written to stdout, and redirected to `/var/log/cron.log` in the example above.

- `cloudcap` - trims recordings from Zoom Cloud to avoid exceeding the storage limit. Leaves `Client.CloudCapacityHardLimit` bytes of the most recent recordings (review the value in config before running!), trashes the rest. Cron job line to run it every day at 5:30 AM (don't mind the paths, they are specific to my setup, use your own):

30 05 * * * cd $HOME/go/src/zoomrs/dist && ./zoomrs-cli --dbg --cmd cloudcap --config ../config/config_cli.yml >> /var/log/cron.log 2>&1

```sh
30 05 * * * cd $HOME/go/src/zoomrs/dist && ./zoomrs-cli --dbg --cmd cloudcap --config ../config/config_cli.yml >> /var/log/cron.log 2>&1
```
- `sync` - syncs recordings from Zoom Cloud. Run it like this:

./zoomrs-cli --dbg --cmd sync --days 1
```sh
./zoomrs-cli --dbg --cmd sync --days 1
```

`--days` parameter used with the value of `1` to sync all the yesterday recordings (1 day before today). This is designed this way to run it as a cron job. Cron job line example:

00 3 * * * cd $HOME/go/src/zoomrs/dist && ./zoomrs-cli --cmd sync --days 1 --config ../config/config_cli.yml >> /var/log/cron.log 2>&1
```sh
00 03 * * * cd $HOME/go/src/zoomrs/dist && ./zoomrs-cli --cmd sync --days 1 --config ../config/config_cli.yml >> /var/log/zoomrs.cron.log 2>&1
```

will sync all recordings from the yesterday every day at 3:00 AM. `--config` option is used to specify the path to the configuration file. `--dbg` option can be used to enable debug logging. Logs are written to stdout, and redirected to `/var/log/cron.log` in the example above.

_* Note that CLI tool uses different configuration file then the server with different Zoom API credentials to avoid spoiling services's auth token when running CLI. Also, running multi-server setup you want to sync recordings only after all servers have downloaded them, so you need to run CLI tool on one of the servers, allow syncing records in CLI config and deny it in servers configs._
> [!NOTE] Using multiple credentials
> CLI tool uses different configuration file then the server with different Zoom API credentials to avoid spoiling services's auth token when running CLI. Also, running multi-server setup you want to sync recordings only after all servers have downloaded them, so you need to run CLI tool on one of the servers, allow syncing records in CLI config and deny it in servers configs.
## Running multiple instances
You can run multiple instances of the service to increase reliability, duplicate downloaded data for redundancy. Each instance should have its own configuration file and its own database file. Each instance should have its own Zoom API credentials. Consider following setup as an example:
Expand All @@ -261,10 +289,17 @@ You can run multiple instances of the service to increase reliability, duplicate
- Run the service with `server.sync_job: false` and `server.download_job: false` so it will just host the API. Run downloader with cron job (see `sync` cmd crontab line example in the previous section). This way you can set the time to run the download job
3. Run cleanup job on one of the instances (see `trash` cmd crontab line example in the previous section). Use configuration file that enumerates all the instances in `server.instances` section. This way cleanup job will check all the instances for consistency and trash/delete recordings from Zoom Cloud only if all the instances have downloaded them. Disable deleting and trashing downloaded recordings (`client.trash_downloaded: false` and `client.delete_downloaded: false` in the configuration file) on every other instance but this one.

### Database backup
Backup database file regularly to prevent data loss. See example shell script at `dist/backup_db.sh`. It can be run as a cron job like this:
> [!NOTE] Copy yesterday's recordings from "Main" instance to "Secondary" instance
Secondary instance can run something like this to copy yesterday's recordings from "Main" instance:
```sh
sleep 1s && date && scp -r server.local:/data/`date --date="yesterday" +%Y-%m-%d` /data/ && date
```

# 0 10 * * * sh $HOME/go/src/zoomrs/backup_db.sh
> [!NOTE] Database backup
Backup database file regularly to prevent data loss. See example shell script at `dist/backup_db.sh`. It can be run as a cron job like this:
```sh
0 10 * * * sh $HOME/go/src/zoomrs/backup_db.sh
```

## Contributing
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change. Check the existing issues to see if your problem is already being discussed or if you're willing to help with one of them. Tests are highly appreciated.
Expand All @@ -276,9 +311,9 @@ Pull requests are welcome. For major changes, please open an issue first to disc
If you have any security issue to report, contact project owner directly at [[email protected]](mailto:[email protected]) or use Issues section of this repository.

## Responsibility
The author of this project is not responsible for any damage caused by the use of this software. Use it at your own risk.
The author of this project is not responsible for any damage caused by the use of this software. Use it at your own risk. However, the software is being used in production at least since May 2023 on a number of devices, processing hundreds of GB of data every day and is considered stable.

## Credits
- [lgr](github.com/go-pkgz/lgr) - simple but effective logging package
- [go-sqlite3](github.com/mattn/go-sqlite3) as a database driver
- [go-pkgz/auth](github.com/go-pkgz/auth) - powerful authentication middleware
- [go-pkgz/auth](github.com/go-pkgz/auth) - powerful authentication middleware
23 changes: 17 additions & 6 deletions dist/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,32 +13,43 @@ Example self-documented configuration file `config.yml` included.
### Foreground mode
Plain and simple `./zoomrs` should load a default `config.yml` file and launch if everything is configured correctly:

./zoomrs
```sh
./zoomrs
```

or specify config file and debug mode:

./zoomrs --config custom_config.yml --dbg
```sh
./zoomrs --config custom_config.yml --dbg
```

To stop the service press `Ctrl+C` (or send `SIGINT`, `SIGTERM` signal to the process)

### Systemd service
1. Configure the service and make sure it runs in foreground mode (see above).
2. Run `make deploy` to build the binary and copy everything where it belongs (see `Makefile` and `zoomrs.service` for details), enable and run the service

make deploy
```sh
make deploy
```

3. Run `make status` to check the status of the service

make status
```sh
make status
```

Log files are located at `/var/log/zoomrs.log` and `/var/log/zoomrs.err` by default.

### CLI Tool
CLI tool command example:

./zoomrs-cli --cmd check --config config.yml
```sh
./zoomrs-cli --cmd check --config config.yml
```

Refer to the [README](https://github.com/parmaster/zoomrs#readme) in main repository to learn more about the CLI tool and its commands.

## Responsibility
The author of this project is not responsible for any damage caused by the use of this software. Use it at your own risk.
The author of this project is not responsible for any damage caused by the use of this software. Use it at your own risk. However, the software is being used in production at least since May 2023 on a number of devices, processing hundreds of GB of data every day and is considered stable.
If you find a bug or have a feature request, please [open an issue](https://github.com/parMaster/zoomrs/issues/new/choose) on GitHub. Thank you!

0 comments on commit 4f905cb

Please sign in to comment.