Skip to content

Commit

Permalink
docs: Add docs for blueprint and configuration
Browse files Browse the repository at this point in the history
  • Loading branch information
stmh committed Dec 16, 2024
1 parent 35a0cfa commit c824d7b
Show file tree
Hide file tree
Showing 6 changed files with 211 additions and 4 deletions.
1 change: 1 addition & 0 deletions docs/.fdocs.js
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@ export default function (defaultConfig) {
"architecture",
"installation",
"configuration",
"cli",
"changelog",
],
});
Expand Down
13 changes: 13 additions & 0 deletions docs/content/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,19 @@ Scotty won't touch these apps, but will show them in the UI and CLI, but you
can't interact with them. You can use the cli-command `app:adopt` to make the
app compatible with scotty.

### Blueprints

Owned apps can adopt blueprints to provide additional functionality. Blueprints
store common tasks to execute on certain events like `app:create`, `app:run` or
`app:destroy`.

These scripts are stored in the `blueprints`-directory of scotty. The scripts
are executed in the running service container of the app. Common tasks could be
for example runnint the deploy command for drupal applications, or clearing
the cache for other apps.

Blueprints can be provided when create in a new app via `app:create`.

## Server-Architecture

Scotty traverses a dedicated folder on the server to find possible apps. If
Expand Down
Binary file added docs/content/assets/cli/app-info.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/content/assets/cli/app-list.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
36 changes: 36 additions & 0 deletions docs/content/cli.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
# the cli

The cli provides a thin wrapper to access the rest-api of scotty. It is
written in rust and provides a simple interface to list, create, update and
destroy apps. You can get some helps by running `scotty --help` and
`scotty --help <command>`.

## List all apps

```shell
scotty --server <SERVER> --token <TOKEN>t app:list
```

Example-output:

![Example output of app:list](assets/cli/app-list.png)

The table contains all apps with their status, uptime and urls. The urls are the
public urls of the apps. The status can be one of the following:

* Running: The app is running
* Stopped: The app is stopped
* Unsupported: The app is not supported by the server

## Get info about an app

```shell
scotty --server <SERVER> --token <TOKEN> app:info <APP>
```

Example-output:

![Example output of app:info](assets/cli/app-info.png)

The command list all services of a specific app and their status. The output
contains also the enabled notification services for that app.
165 changes: 161 additions & 4 deletions docs/content/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,10 @@
Configuration on the server side is done using some toml files inside the
config folder, see below.

The CLI does not have any configuration. All it needs to know is the URL of the
The cli does not have any configuration. All it needs to know is the URL of the
server and the api token to authenticate against the server.

## the CLI
## the cli

Run `scottyctl` with the follwinng options:

Expand All @@ -16,7 +16,7 @@ scottyctl --server https://loclahost:21342 --token my-secret
```

You can also set the environment variables `SCOTTY_SERVER` and
`SCOTTY_ACCESS_TOKEN` to store the server and token for the CLI.
`SCOTTY_ACCESS_TOKEN` to store the server and token for the cli.

To check if the server and access-token works, run the command `app:list`:

Expand Down Expand Up @@ -89,7 +89,7 @@ scheduler:
other useful information. The higher the setting the longer you can inspect
the output of commands in the UI

## Apps
### Apps

```
apps:
Expand All @@ -100,3 +100,160 @@ apps:
* `domain_suffix` The suffix for auto-generated domains. Set this to the domain
you want to use for your apps. App-domains are constructed by the service- and
the app-name, when a custom domain is not provided.
* `root_folder` The folder where the apps are stored. The default is `./apps`.
If you run scotty in a docker container, and mount the apps-folder into the
container, make sure that both paths are the same. Otherwise docker-compose
can't run the apps, as there is a mismatch between the local path and the
path on the host, where the docker daemon is running.
### docker
Scotty uses docker to inspect running docker apps. For this to work it needs to
communicate with the docker daemon
```yaml
docker:
connection: local # local, socket or http, see bollard docs
registries:
example_registry:
registry: https://registry.example.com
username: "registry"
password: "registry"
example_2_registry:
...
```

* `connection` The connection to the docker daemon. The default is `local`. Other
possible values are `socket` and `http`. See the bollard documentation for
more information.
* `registries` A list of registries to pull images from. The key is the name of
the registry, the value is a map with the keys `registry`, `username` and
`password`. The password is stored in plain text. If you want to use a
registry with a token, you need to provide the token as password.

The key for the registry is used when creating a new app, so scotty knows
where to pull the image from, see the docs for `app:create`

If you do not want to store the password in plain text, you can provide the
password as an environment variable. Check the override section for more
information.

### Loadbalancer

Scotty can work with different loadbalancers, currently with Traefik (preferred)
and Haproxy-config (deprecated).

```yaml
load_balancer_type: Traefik #HaproxyConfig or Traefik
traefik:
network: "proxy"
use_tls: true
certresolver: "myresolver"
haproxy:
use_tls: true
```
* `load_balancer_type` The loadbalancer to use. Use `Traefik` or `HaproxyConfig`

#### Traefik

* `network` The network to use for the communication between scotty and traefik.
The default is `proxy`. If you use a different network, make sure to create
the network before starting scotty.
Scotty will also add the network to all public services of your app when you
create or adopt an app, so traefik can access the public services of the app.
* `use_tls` If set to true, scotty will create the necessary labels for traefik
to use tls. The default is true.
* `certresolver` The certresolver to use for the tls-certificate. The
certresolver must be configured in traefik. The default is `myresolver` shown
also in the example `docker-compose.yml` from the [installation-documentation](installation.md)

#### Haproxy-config

* `use_tls` If set to true, scotty will create the necessary environment variables
for haproxy-config to use tls.


### Blueprints

Blueprints are a way to run certain tasks after specific events happened, like
`app:create`, `app:run` or `app:destroy`. They are stored in `config/blueprints`
and can be adopted by apps. They are stored as separate files in the
`config/blueprints`-folder. Scotty is using the key of the blueprint to associate
the blueprint with an app.

Here's an example blueprint:

```yaml
apps:
blueprints:
drupal-lagoon:
name: "Drupal using lagoon base images"
description: "A simple Drupal application using lagoon base images (cli, php, nginx)"
required_services:
- cli
- php
- nginx
public_services:
nginx: 8080
actions:
post_create:
cli:
- drush deploy
post_rebuild:
cli:
- drush deploy
post_run:
cli:
- drush uli
```

* `name` The name of the blueprint
* `description` A short description of the blueprint
* `required_services` A list of services that are required for the blueprint to
work. If one of the services is missing, scotty will throw an error when an
app tries to adopt the blueprint.
* `public_services` A list of services that should be exposed to the public. The
key is the service name, the value is the port to expose.
* `actions` A list of action-hooks and their corresponding commands. The
following hooks are available:
* `post_create` Run after the app was created
* `post_rebuild` Run after the app was rebuilt
* `post_run` Run after the app was started
* `post_destroy` Run after the app was destroyed
The key is the service name, the value is a list of commands to run on that
service.

If you create a new app via `app:create` or the REST-API, you can provide the
blueprint to associate with your app.

### Overrides

The default configuration is stored in `config/default.yaml`. You can override
all or parts of the documentation by creating a file `config/local.yaml` and
replace the values you want to override.

As an alternative you can override the configuration by setting environment
variables, this is especiall useful for sensitive data like passwords.

The environment variables must be prefixed with `SCOTTY__` and the keys must be
concatenated with double underscores. For example to override the access token
you can set the environment variable `SCOTTY__API__ACCESS_TOKEN`.

Rule of thumb is: If you want to override a key, replace the dots with double
underscores and prefix the key with `SCOTTY__`.

### Example

| name of value in the config file | environment variable |
|---------------------------------------------------|----------------------------------------------------------|
| `debug` | `SCOTTY__DEBUG` |
| `api.access_token` | `SCOTTY__API__ACCESS_TOKEN` |
| `api.bind_address` | `SCOTTY__API__BIND_ADDRESS` |
| `docker.registries.example_registry.password` | `SCOTTY__DOCKER__REGISTRIES__EXAMPLE_REGISTRY__PASSWORD` |
| `apps.domain_suffix` | `SCOTTY__APPS__DOMAIN_SUFFIX` |
| `load_balancer_type` | `SCOTTY__LOAD_BALANCER_TYPE` |
| `traefik.network` | `SCOTTY__TRAEFIK__NETWORK` |

Scotty will print out the resolved configuration on startup, so you can check
for any errors.

0 comments on commit c824d7b

Please sign in to comment.