container-server/README.md

# Containered Server

Private server based on containers and compose

## Disclaimer:

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

## Repo Structure

- `./services` **Service definitions**
  - One subfolder per service with:
    - `docker-compose.yml` for this service and its direct dependencies (e.g. databases or workers)
    - Additional config files, possibly as template (see below)
- `./setup` **Host setup**
  - Setup information about a possible alpine host system
- `./tasks` **Task definitions**
  - `compose.yml`: Container related tasks e.g. starting, updating, or reading logs
  - `dev.yml`: Useful tasks during development, e.g. adding locally signed certificates into running containers
  - `host.yml`: Tasks related to host system maintenance
  - `manage.yml`: Tasks about managing the list of enabled services
  - `services.yml`: Tasks for specific services
  - `utils.yml`: Utility tasks, mainly used as part of other tasks

## Requirements

- `envsubst`, most likely via gettext package. Refer to your distros docs.
- docker
- docker-compose

## Data Persistence

All data SHALL BE stored in `$BASE_DIR` (defaults to `/srv`), one subfolder per service.

## Secrets & Configuration

Copy from `.env.sample` and fill in your values.

## Deploy

Enable services with `./task mgmt:enable <service directory name>` and check enabled services with `./task mgmt:ls-enable`.

Then run

```sh
./task compose:up
```

List other tasks

```sh
./task -l
```

## Templating

Filename pattern: `*.template.*`

Files matching the pattern are copied with the ".template." infix removed (e.g. forgejo.template.ini -> forgejo.ini).  
Variables are replaced using shell substitution syntax (`${VARIABLE_NAME_HERE}`) using the current environment and values from `.env`.

_Note:_ Variables cannot contain other variables, only one level of template is possible.

## Host Setup

A possible alpine based host setup is described in [/setup](./setup/README.md).

## Backup

Notes on backup and a possible config using borgmatic can be found in [/setup/backup](./setup/backup/README.md)