|
6 | 6 |
|
7 | 7 | --- |
8 | 8 |
|
9 | | -A single application to spin up your entire dev stack. |
10 | | - |
11 | | -## Features |
| 9 | +Spin up your entire dev stack with one command. |
12 | 10 |
|
13 | 11 | `StackUp` offers many features and advanced functionality. Here are some of the highlights: |
14 | 12 |
|
15 | 13 | - Define tasks that run on startup, shutdown, or on a schedule. |
16 | 14 | - Customize tasks and preconditions using javascript. |
17 | 15 | - Run tasks on a cron schedule, i.e. running `php artisan schedule:run` once every minute. |
18 | | -- Load shared configurations with remote file includes via http or S3. |
19 | | -- Optional checksum validation of remotely included files. |
20 | | -- Fast in-memory cache for skipping http requests when possible. |
21 | | -- Http request gateway that prevents unwanted access to remote files, domains or content types. |
22 | | -- Domain-specific http header configuration. |
| 16 | +- Load remote configurations via http or S3. |
| 17 | +- Fast in-memory cache skips http requests when possible. |
| 18 | +- Http request gateway prevents unwanted access to remote urls, domains and content types. |
| 19 | +- Send notifications with Telegram and Slack integrations. |
| 20 | + |
| 21 | +## Table of Contents |
| 22 | + |
| 23 | +- [StackUp](#stackup) |
| 24 | + - [Table of Contents](#table-of-contents) |
| 25 | + - [About](#about) |
| 26 | + - [Running StackUp](#running-stackup) |
| 27 | + - [Configuration](#configuration) |
| 28 | + - [Configuration: Settings](#configuration-settings) |
| 29 | + - [Configuration: Settings: Gateway](#configuration-settings-gateway) |
| 30 | + - [Configuration: Settings: Domains](#configuration-settings-domains) |
| 31 | + - [Configuration: Settings: Notifications](#configuration-settings-notifications) |
| 32 | + - [Configuration: Settings: Notifications: Telegram](#configuration-settings-notifications-telegram) |
| 33 | + - [Configuration: Settings: Notifications: Slack](#configuration-settings-notifications-slack) |
| 34 | + - [Configuration: Environment Variables](#configuration-environment-variables) |
| 35 | + - [Configuration: Includes](#configuration-includes) |
| 36 | + - [Configuration: Preconditions](#configuration-preconditions) |
| 37 | + - [Configuration: Tasks](#configuration-tasks) |
| 38 | + - [Configuration: Startup \& Shutdown](#configuration-startup--shutdown) |
| 39 | + - [Configuration: Servers](#configuration-servers) |
| 40 | + - [Configuration: Scheduler](#configuration-scheduler) |
| 41 | + - [Example Configurations](#example-configurations) |
| 42 | + - [Integrations](#integrations) |
| 43 | + - [Integration: dotenv-vault](#integration-dotenv-vault) |
| 44 | + - [Integration: Telegram Notifications](#integration-telegram-notifications) |
| 45 | + - [Integration: Slack Notifications](#integration-slack-notifications) |
| 46 | + - [Scripting](#scripting) |
| 47 | + - [Available Functions](#available-functions) |
| 48 | + - [Script Classes](#script-classes) |
| 49 | + - [`ComposerJson`](#composerjson) |
| 50 | + - [`PackageJson`](#packagejson) |
| 51 | + - [`RequirementsTxt`](#requirementstxt) |
| 52 | + - [`SemVer`](#semver) |
| 53 | + - [Environment Variables](#environment-variables) |
| 54 | + - [Dynamic Tasks](#dynamic-tasks) |
| 55 | + - [Initialization Script](#initialization-script) |
| 56 | + - [Setup](#setup) |
| 57 | + - [Building the project](#building-the-project) |
| 58 | + - [Changelog](#changelog) |
| 59 | + - [Contributing](#contributing) |
| 60 | + - [Security Vulnerabilities](#security-vulnerabilities) |
| 61 | + - [Credits](#credits) |
| 62 | + - [License](#license) |
23 | 63 |
|
24 | 64 | ## About |
25 | 65 |
|
@@ -182,27 +222,53 @@ domains: |
182 | 222 | - 'Accept: application/vnd.github.v3+json' |
183 | 223 | ``` |
184 | 224 |
|
185 | | -### Configuration: Environment Variables |
| 225 | +#### Configuration: Settings: Notifications |
186 | 226 |
|
187 | | -Environment variables can be defined in the optional `env` section of the configuration file. These variables can be referenced in other sections of the configuration file using the `env()` function or by prefixing the variable name with `$` (e.g. `$MY_VAR`). |
| 227 | +StackUp provides the ability to send notifications via several integrations. |
188 | 228 |
|
189 | 229 | ```yaml |
190 | | -env: |
191 | | - - MY_ENV_VAR_ONE=test1234 |
192 | | - - MY_ENV_VAR_TWO=1234test |
| 230 | +settings: |
| 231 | + notifications: |
| 232 | + # integration1 settings |
| 233 | + # integration2 settings, etc. |
193 | 234 | ``` |
194 | 235 |
|
195 | | -#### Integration: dotenv-vault |
| 236 | +#### Configuration: Settings: Notifications: Telegram |
196 | 237 |
|
197 | | -`StackUp` supports loading encrypted values from `.env.vault` files (see the [dotenv-vault website](https://vault.dotenv.org)). |
| 238 | +To send notifications via Telegram, add a `telegram` section to the `notifications` section of the configuration file. The `telegram` section should contain an `api-key` and a `chat-ids` field. The `api-key` field should contain the Telegram bot token, and the `chat-ids` field should be an array of chat ids of the users or groups to send notifications to. The chat ids may either be a string, number, or an environment variable that contains a chat id. |
198 | 239 |
|
199 | | -To load a `.env.vault` file, add an entry to the `env` section named `dotenv://vault`. This item will cause the `.env.vault` file to |
200 | | -be loaded into the environment, if it exists. If it does not exist, no action is taken. |
| 240 | +```yaml |
| 241 | +settings: |
| 242 | + notifications: |
| 243 | + telegram: |
| 244 | + api-key: $TELEGRAM_API_KEY |
| 245 | + chat-ids: [$TELEGRAM_CHAT_ID1, $TELEGRAM_CHAT_ID2] |
| 246 | +``` |
| 247 | + |
| 248 | +For more information on the Telegram integration, see the [Telegram Notifications](#integration-telegram-notifications) section of the [Integrations](#integrations) documentation. |
| 249 | + |
| 250 | +#### Configuration: Settings: Notifications: Slack |
| 251 | + |
| 252 | +To send notifications via Slack, add a `slack` section to the `notifications` section of the configuration file. The `slack` section should contain `webhook-url` and `channel-ids` fields. The `webhook-url` field should contain the Slack webhook url to send notifications to, and the `channel-ids` field should be an array of channel names to send notifications to. |
| 253 | + |
| 254 | +```yaml |
| 255 | +settings: |
| 256 | + notifications: |
| 257 | + slack: |
| 258 | + webhook-url: $SLACK_WEBHOOK_URL |
| 259 | + channel-ids: [$SLACK_CHANNEL_1, $SLACK_CHANNEL_2] |
| 260 | +``` |
| 261 | + |
| 262 | +For more information about the Slack integration, see the [Slack Notifications](#integration-slack-notifications) section of the [Integrations](#integrations) documentation. |
| 263 | + |
| 264 | +### Configuration: Environment Variables |
| 265 | + |
| 266 | +Environment variables can be defined in the optional `env` section of the configuration file. These variables can be referenced in other sections of the configuration file using the `env()` function or by prefixing the variable name with `$` (e.g. `$MY_VAR`). |
201 | 267 |
|
202 | 268 | ```yaml |
203 | 269 | env: |
204 | 270 | - MY_ENV_VAR_ONE=test1234 |
205 | | - - dotenv://vault # loads .env.vault, if it exists |
| 271 | + - MY_ENV_VAR_TWO=1234test |
206 | 272 | ``` |
207 | 273 |
|
208 | 274 | ### Configuration: Includes |
@@ -410,6 +476,51 @@ See the [example configuration](./templates/stackup.dist.yaml) for a more comple |
410 | 476 |
|
411 | 477 | Working on a standalone Laravel application? Check out the [example laravel configuration](./templates/stackup.laravel.yaml). |
412 | 478 |
|
| 479 | +## Integrations |
| 480 | + |
| 481 | +StackUp supports several integrations that provide additional functionality. |
| 482 | + |
| 483 | +### Integration: dotenv-vault |
| 484 | + |
| 485 | +`StackUp` includes an integration for `dotenv-vault` and loading encrypted values from `.env.vault` files (see the [dotenv-vault website](https://vault.dotenv.org)). |
| 486 | + |
| 487 | +To load a `.env.vault` file, add an entry to the `env` section named `dotenv://vault`. This item will cause the `.env.vault` file to |
| 488 | +be loaded into the environment, if it exists. If it does not exist, no action is taken. |
| 489 | + |
| 490 | +```yaml |
| 491 | +env: |
| 492 | + - MY_ENV_VAR_ONE=test1234 |
| 493 | + - dotenv://vault # loads .env.vault, if it exists |
| 494 | +``` |
| 495 | + |
| 496 | +### Integration: Telegram Notifications |
| 497 | + |
| 498 | +`StackUp` includes an integration for sending notifications via Telegram. To configure the integration, see the [Telegram Notifications](#configuration-settings-notifications-telegram) section of the [Configuration: Settings](#configuration-settings) documentation. |
| 499 | + |
| 500 | +Notifications are sent using javascript: |
| 501 | + |
| 502 | +```js |
| 503 | +// send a notification to all configured chat ids |
| 504 | +notifications.Telegram().Message("hello from stackup, test 123").Send() |
| 505 | +
|
| 506 | +// send a notification to a specific chat id |
| 507 | +notifications.Telegram().Message("hello from stackup, test 456").To($TELEGRAM_CHAT_ID_1).Send() |
| 508 | +``` |
| 509 | + |
| 510 | +### Integration: Slack Notifications |
| 511 | + |
| 512 | +`StackUp` includes an integration for sending messages to Slack channels. To configure the integration, see the [Slack Notifications](#configuration-settings-notifications-slack) section of the [Configuration: Settings](#configuration-settings) documentation. |
| 513 | + |
| 514 | +Notifications are sent using javascript: |
| 515 | + |
| 516 | +```js |
| 517 | +// send a notification to all configured chat ids |
| 518 | +notifications.Slack().Message("hello from stackup, test 123").Send() |
| 519 | +
|
| 520 | +// send a notification to a specific chat id |
| 521 | +notifications.Slack().Message("hello from stackup, test 456").To($SLACK_CHANNEL_1).Send() |
| 522 | +``` |
| 523 | + |
413 | 524 | ## Scripting |
414 | 525 |
|
415 | 526 | Many of the fields in a `Task` can be defined using javascript. To specify an expression to be evaluated, wrap the content in double braces: `{{ env("HOME") }}`. |
|
0 commit comments