diff --git a/docs/.fdocs.js b/docs/.fdocs.js index 8bfdc46..fb11d72 100644 --- a/docs/.fdocs.js +++ b/docs/.fdocs.js @@ -27,6 +27,7 @@ export default function (defaultConfig) { "architecture", "installation", "configuration", + "cli", "changelog", ], }); diff --git a/docs/content/architecture.md b/docs/content/architecture.md index 6e2ec68..137cb6f 100644 --- a/docs/content/architecture.md +++ b/docs/content/architecture.md @@ -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 diff --git a/docs/content/assets/cli/app-info.png b/docs/content/assets/cli/app-info.png new file mode 100644 index 0000000..72faff1 Binary files /dev/null and b/docs/content/assets/cli/app-info.png differ diff --git a/docs/content/assets/cli/app-list.png b/docs/content/assets/cli/app-list.png new file mode 100644 index 0000000..4bd8b85 Binary files /dev/null and b/docs/content/assets/cli/app-list.png differ diff --git a/docs/content/cli.md b/docs/content/cli.md new file mode 100644 index 0000000..bacecc4 --- /dev/null +++ b/docs/content/cli.md @@ -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 `. + +## List all apps + +```shell +scotty --server --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 --token app:info +``` + +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. diff --git a/docs/content/configuration.md b/docs/content/configuration.md index 6934639..921e802 100644 --- a/docs/content/configuration.md +++ b/docs/content/configuration.md @@ -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: @@ -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`: @@ -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: @@ -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.