https://github.com/olegwock/surek
Utility built on top of Docker Compose to make managing self-hosted services easier
https://github.com/olegwock/surek
Last synced: 4 months ago
JSON representation
Utility built on top of Docker Compose to make managing self-hosted services easier
- Host: GitHub
- URL: https://github.com/olegwock/surek
- Owner: OlegWock
- License: gpl-3.0
- Created: 2024-07-18T13:22:55.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2024-07-21T09:37:44.000Z (about 1 year ago)
- Last Synced: 2025-04-06T15:54:29.858Z (6 months ago)
- Language: TypeScript
- Homepage:
- Size: 112 KB
- Stars: 4
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Surek
Surek is a utility built on top of Docker Compose to make managing self-hosted services easier.
It manages Caddy reverse proxy for your containers, can back up Docker volumes, and comes with Portainer and Netdata to easily manage and monitor your server.
## Install
Surek requires that you have Docker and Node.js (tested with v22) installed. It also assumes you have a domain pointed to your server.
Run this command to install Surek. If your Docker installation requires using `sudo`, install Surek with `sudo` too.
```
npm install -g surek
```
## Usage
Create a folder where you wish to keep your config and service definitions (stacks). If you intend to push this folder into git, add this line to `.gitignore`
```
surek-data
```
Create a file named `surek.yml`. This is main config.
```yaml
# Root domain
root_domain: example.com
# Used for Netdata, also can be used in stack configs
default_auth: surek:test42
# Optional. Backup volumes into S3 compatible storage
backup:
password: "test42"
s3_endpoint: "s3.eu-central-003.backblazeb2.com"
s3_bucket: "surek-backup"
s3_access_key: "beep"
s3_secret_key: "boop"
# Optional. GitHub personal access token. Enables pulling stacks from github (including private repositories)
github:
pat: secret
```
With central config in place, you can start system containers. Those include Caddy, Portainer, Netdata and everything else Surek needs to work properly.
```
# Run with sudo if your Docker installation requires it
surek system start
```
After system containers started, you can verify their status with command:
```
surek status
```
Visit `portainer.` to finish Portainer installation in 5 minutes, or it will lock you out and require removing volume and re-installing it.
Besides Portainer, there will be a `netdata.` to monitor your server.
Next are stacks. Stack is a collection of services that are related. In Surek, stacks are stored in the `stacks` folder (create it!) and defined by the `surek.stack.yml` file. This file defines the location of the compose file and other stack parameters.
```yaml
name: any-name-you-want
# All files we need are already here. Convenient for services that have their Docker images in the registry
source:
type: local
# Or pull service from Github
# type: github
# #ref is git reference (commit, tag, branch, etc) and is optional, will use HEAD by default
# slug: OlegWock/repo-name#ref
# Path to compose file relative to stack config in case of local source, or relative to repo root for github sources
compose_file_path: "./docker-compose.yml"
# Optional. Services to expose as subdomains
public:
# You can use and other variables in configs (about them later)
- domain: owncloud.
target: owncloud:8080 # :
auth: admin:password123 # Optional. Adds Basic HTTP auth to subdomain
# Optional. Environment variables to add to particular (or all) container
env:
by_container:
owncloud: # service name
- OWNCLOUD_DOMAIN=owncloud.
- OWNCLOUD_TRUSTED_DOMAINS=owncloud.
shared:
- EXAMPLE=1
# Optional. Exclude certain volumes from backup
backup:
exclude_volumes:
- volume-name
```
And the last important piece is the compose file itself. You write compose files as you would normally, except a few specifics.
* You don't need to expose any ports from the container
* You should use named volumes (not bind mounts) if you want them to be backuped. It's also important to not set any parameters for these volumes (like driver or driver parameters), as they will be overwritten by Surek.
* All services (from all stacks) will be placed on the same internal network, so if you have any code depending on the container hostname (e.g., connecting a database to an app), make sure you set the hostname explicitly or use a unique service name for them to avoid collisions with common services (like MySQL, Redis, etc.) from other stacks.
With that finished, you can start stack with this command:
```
surek deploy
```
This will deploy the stack. What happens under the hood is:
1. If using GitHub, Surek will pull the latest version into a temporary folder.
2. Surek will copy all files from the stack folder (the folder where `surek.stack.yml` is stored) into a temporary folder (overwriting files and merging folders). If you need to overwrite or add any files to the stack pulled from the GitHub repo, this is the way.
3. Surek will read the compose file (by path specified in stack config), transform it by adding containers to the network, updating volume configuration, etc., and save it as `docker-compose.surek.yml`.
4. Docker Compose will be used to deploy the stack.
To stop stack:
```
surek stop
```
To start a stack again without re-pulling and transforming the compose file:
```
surek start
```
## Examples
You can find example stacks in the [example-stacks](example-stacks/) folder.
## Variables
In Stack config, it's possible to use variables in `public.domain`, `public.auth`, and `env` sections. List of available variables:
* `` – root domain, as defined in `surek.yml`.
* `` – shortcut for `:`.
* `` – default user, as defined in `surek.yml`.
* `` – default password, as defined in `surek.yml`.
And those are available only if you have `backup` configured in `surek.yml`:
* ``
* ``
* ``
* ``
* ``