Skip to content

Commit 6d49ac4

Browse files
author
Lasim
committed
Add comprehensive documentation for DeployStack configuration and usage
- Introduced DeployStack Config File Reference detailing the config.yml schema and customization options. - Created .deploystack Directory Reference to explain the structure and purpose of the .deploystack directory. - Documented Docker Compose Requirements outlining the necessary conditions for using Docker Compose with DeployStack. - Explained Environment Variables management in DeployStack, including usage in Docker configurations. - Provided a detailed Getting Started guide for deploying Docker applications with DeployStack. - Added GitHub Application documentation for integrating DeployStack with GitHub for automatic updates. - Outlined the Infrastructure as Code Lifecycle for managing template updates and synchronization. - Developed a Branch Strategy guide for implementing multi-branch deployment strategies. - Documented the One-Click Deploy feature for simplified application deployment across cloud providers. - Compiled a Troubleshooting guide for common issues encountered during repository submission and deployment.
1 parent fcf0523 commit 6d49ac4

11 files changed

Lines changed: 48 additions & 56 deletions

tmp/deploystack/application-logo-configuration.mdx renamed to docs/deploystack/application-logo-configuration.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ Add a custom logo to make your application stand out in the DeployStack catalog.
99

1010
## Adding Your Logo
1111

12-
Configure your logo in `.deploystack/config.yml` - [DeployStack Configuration File Reference](/docs/deploystack/deploystack-config-file.md):
12+
Configure your logo in `.deploystack/config.yml` - [DeployStack Configuration File Reference](/docs/deploystack/deploystack-config-file):
1313

1414
```yaml
1515
application:

tmp/deploystack/deploystack-config-file.mdx renamed to docs/deploystack/deploystack-config-file.mdx

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
11
---
22
title: DeployStack Config File Reference
33
description: Documentation for DeployStack's config.yml schema. Customize your application's presentation with automatic IDE validation and flexible repository metadata overrides.
4-
menuTitle: DeployStack Config File
54
---
65

76
# DeployStack Configuration File Reference
@@ -57,7 +56,7 @@ The override process follows this order:
5756

5857
### Branch Deployment Settings
5958

60-
Before configuring multiple branch deployments, ensure you have installed the [DeployStack Repository Sync GitHub App](/docs/deploystack/github-application.md), as it's required for branch monitoring and template updates.
59+
Before configuring multiple branch deployments, ensure you have installed the [DeployStack Repository Sync GitHub App](/docs/deploystack/github-application), as it's required for branch monitoring and template updates.
6160

6261
You can configure multiple branch deployments using the `deployment.branches` section:
6362

@@ -110,7 +109,7 @@ This is especially useful for projects that maintain multiple active versions si
110109

111110
The optional `exclude_providers` array allows you to specify which cloud providers should be excluded from template generation for particular branches. This is useful when certain features in a branch version may not be compatible with specific cloud providers. Valid provider codes are:
112111

113-
Please check our [current supported provider list here](/docs/docker-to-iac/parser/index.md).
112+
Please check our [current supported provider list here](/docs/docker-to-iac/parser/index).
114113

115114
For example, if your beta version uses features only supported in DigitalOcean, you might exclude the other providers:
116115

@@ -257,4 +256,4 @@ deployment:
257256

258257
### Minimal Configuration example for logo update
259258

260-
Please visit our [Application Logo Configuration](/docs/deploystack/application-logo-configuration.md) page.
259+
Please visit our [Application Logo Configuration](/docs/deploystack/application-logo-configuration) page.

tmp/deploystack/deploystack-configuration-directory.mdx renamed to docs/deploystack/deploystack-configuration-directory.mdx

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,15 @@
11
---
22
title: .deploystack Directory Reference
33
description: Technical guide for setting up the .deploystack directory to manage Infrastructure as Code template generation and updates across your repository.
4-
menuTitle: .deploystack Directory
54
---
65

76
# .deploystack Directory Reference
87

9-
The `.deploystack` directory in your repository contains configuration files that DeployStack uses to generate and maintain your Infrastructure as Code templates. Creating this repo allows you to enable the [lifecycle of IaC](/docs/deploystack/iac-lifecycle.md). The deploystack configurations repo only makes sense if you also [install DeployStack GitHub app](/docs/deploystack/github-application.md). Otherwise, changes to DeployStack backend will not be recognized.
8+
The `.deploystack` directory in your repository contains configuration files that DeployStack uses to generate and maintain your Infrastructure as Code templates. Creating this repo allows you to enable the [lifecycle of IaC](/docs/deploystack/iac-lifecycle). The deploystack configurations repo only makes sense if you also [install DeployStack GitHub app](/docs/deploystack/github-application). Otherwise, changes to DeployStack backend will not be recognized.
109

11-
> [!NOTE]
12-
> `.deploystack` directory is optional. You don't need to create it to submit your repository to deploystack.io.
10+
<Callout>
11+
`.deploystack` directory is optional. You don't need to create it to submit your repository to deploystack.io.
12+
</Callout>
1313

1414
## Directory Structure
1515

@@ -24,7 +24,7 @@ The `.deploystack` directory in your repository contains configuration files tha
2424

2525
### DeployStack Configuration File
2626

27-
Please read more at [DeployStack Configuration File Reference](/docs/deploystack/deploystack-config-file.md).
27+
Please read more at [DeployStack Configuration File Reference](/docs/deploystack/deploystack-config-file).
2828

2929
### Docker Configuration
3030

@@ -52,11 +52,11 @@ docker run -d -p 80:80 nginx:alpine
5252

5353
### Environment Variables
5454

55-
Please read more from our [environment variables](/docs/deploystack/docker-environment-variables.md) page.
55+
Please read more from our [environment variables](/docs/deploystack/docker-environment-variables) page.
5656

5757
## Automatic Updates
5858

59-
When the [DeployStack GitHub App](/docs/deploystack/github-application.md) is installed:
59+
When the [DeployStack GitHub App](/docs/deploystack/github-application) is installed:
6060

6161
1. Changes to specific (`docker-compose.yml` & `docker-run.txt`) file in `.deploystack/` trigger template updates
6262
2. Updates only process when changes occur on the default branch
@@ -66,6 +66,6 @@ When the [DeployStack GitHub App](/docs/deploystack/github-application.md) is in
6666

6767
- The `.deploystack` directory is **optional**
6868
- Without this directory, automatic template updates are **not** available
69-
- You can add the directory and install the [DeployStack GitHub Sync App](/docs/deploystack/github-application.md) at any time
70-
- [Environment variables](/docs/deploystack/docker-environment-variables.md) and [DeployStack config](/docs/deploystack/deploystack-config-file.md) are optional components
69+
- You can add the directory and install the [DeployStack GitHub Sync App](/docs/deploystack/github-application) at any time
70+
- [Environment variables](/docs/deploystack/docker-environment-variables) and [DeployStack config](/docs/deploystack/deploystack-config-file) are optional components
7171
- Only one Docker configuration file should be used (either compose or run)

tmp/deploystack/docker-compose-requirements.mdx renamed to docs/deploystack/docker-compose-requirements.mdx

Lines changed: 9 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
11
---
22
title: Docker Compose Requirements
33
description: Technical requirements for using Docker Compose with DeployStack's cloud deployment automation. Includes supported properties, registry options, and validation rules.
4-
menuTitle: Docker Compose Requirements
54
---
65

76
# Docker Compose Requirements
@@ -13,7 +12,7 @@ DeployStack is designed to work with Docker Compose files that meet specific req
1312
Your `docker-compose.yml` file must:
1413

1514
1. Use pre-built Docker images
16-
2. Reference public images from Docker Hub or another registries -> check [Supported Registries](/docs/docker-to-iac/supported-registries.md)
15+
2. Reference public images from Docker Hub or another registries -> check [Supported Registries](/docs/docker-to-iac/supported-registries)
1716
3. Be a valid Docker Compose file (version 3 and above)
1817

1918
Your docker-compose file does not necessarily have to be called `docker-compose.yml` and does not have to be located in the root directory. You can rename your docker compose file and store it in any sub directory.
@@ -26,7 +25,7 @@ If your docker compose file is not located in the root directory and has not `do
2625

2726
Your services must specify the `image` property. For example:
2827

29-
```yaml [docker-compose.yml]
28+
```yaml title="docker-compose.yml"
3029
# ✅ Supported
3130
services:
3231
app:
@@ -39,7 +38,7 @@ services:
3938
4039
We do not support services that use the `build` directive:
4140

42-
```yaml [docker-compose.yml]
41+
```yaml title="docker-compose.yml"
4342
# ❌ Not Supported
4443
services:
4544
app:
@@ -54,7 +53,7 @@ The infrastructure templates we generate require specific, immutable container i
5453

5554
## Supported Docker Compose Properties
5655

57-
We currently support these Docker Compose properties -> please check [Supported Docker Compose Variables](/docs/docker-to-iac/supported-docker-compose-variables.md).
56+
We currently support these Docker Compose properties -> please check [Supported Docker Compose Variables](/docs/docker-to-iac/supported-docker-compose-variables).
5857

5958
### Kubernetes/Helm
6059

@@ -75,19 +74,19 @@ DeployStack can handle Docker Compose files with multiple services, but support
7574
- Others will only deploy the first service in your compose file
7675
- Kubernetes (Helm) supports multi-service deployments with each service becoming a separate Deployment
7776

78-
Check the specific [Multi Services Support](/docs/docker-to-iac/multi-services-support.md) for details about multi-service support.
77+
Check the specific [Multi Services Support](/docs/docker-to-iac/multi-services-support) for details about multi-service support.
7978

8079
## Working with Private Images
8180

8281
Currently, DeployStack only supports public images from Docker Hub. If you need to use private images:
8382

84-
1. Make your images public on Docker Hub or [other supported registries](/docs/docker-to-iac/supported-registries.md)
83+
1. Make your images public on Docker Hub or [other supported registries](/docs/docker-to-iac/supported-registries)
8584
2. Update your docker-compose.yml to reference the public images
8685
3. Submit your repository to DeployStack
8786

8887
## Environment Variables
8988

90-
Please read more from our [environment variables](/docs/deploystack/docker-environment-variables.md) page.
89+
Please read more from our [environment variables](/docs/deploystack/docker-environment-variables) page.
9190

9291
## Validation
9392

@@ -99,5 +98,5 @@ When you submit your repository, we perform these checks:
9998

10099
## Next Steps
101100

102-
- See how [One-Click Deploy](/docs/deploystack/one-click-deploy.md) works
103-
- Check the [Troubleshooting](/docs/deploystack/troubleshooting.md) guide if you run into issues
101+
- See how [One-Click Deploy](/docs/deploystack/one-click-deploy) works
102+
- Check the [Troubleshooting](/docs/deploystack/troubleshooting) guide if you run into issues

tmp/deploystack/docker-environment-variables.mdx renamed to docs/deploystack/docker-environment-variables.mdx

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
11
---
22
title: Environment Variables in DeployStack
33
description: Learn how to manage environment variables in DeployStack using the .deploystack/env file. Support for Docker Compose, Docker run commands, and default values.
4-
menuTitle: Environment Variables
54
---
65

76
# Environment Variables in DeployStack

tmp/deploystack/getting-started.mdx renamed to docs/deploystack/getting-started.mdx

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
11
---
22
title: Getting Started with DeployStack
33
description: Start deploying Docker applications across cloud providers with DeployStack. Step-by-step guide to generating infrastructure templates from Docker configurations.
4-
menuTitle: Getting Started
54
---
65

76
# Getting Started with DeployStack
@@ -100,7 +99,7 @@ Create a `.deploystack` directory in your repository with these components:
10099
- `docker-run.txt`: Alternative to compose file, contains your Docker run command
101100
- Only one of these files should be present
102101

103-
For more configuration options please check our [.deploystack Directory Reference](/docs/deploystack/deploystack-configuration-directory.md).
102+
For more configuration options please check our [.deploystack Directory Reference](/docs/deploystack/deploystack-configuration-directory).
104103

105104
### GitHub App Integration
106105

@@ -190,6 +189,6 @@ After template generation:
190189

191190
## Need Additional Help?
192191

193-
- Review our detailed [Troubleshooting Guide](/docs/deploystack/troubleshooting.md)
192+
- Review our detailed [Troubleshooting Guide](/docs/deploystack/troubleshooting)
194193
- Join our active [Discord Community](https://discord.gg/UjFWwByB)
195194
- Submit issues on GitHub to our [Feedback repository](https://github.com/deploystackio/feedback)

tmp/deploystack/github-application.mdx renamed to docs/deploystack/github-application.mdx

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
11
---
22
title: GitHub Application
33
description: Keep Docker configurations and deployment templates in sync with DeployStack's GitHub App. Updates templates automatically when files change.
4-
menuTitle: GitHub Application
54
---
65

76
# GitHub App Integration
@@ -12,13 +11,14 @@ The DeployStack GitHub App ensures your Infrastructure as Code (IaC) templates r
1211

1312
When you install the [DeployStack Repository Sync](https://github.com/apps/deploystack-repository-sync) app, it monitors specific files in your repository:
1413

15-
- `.deploystack/` directory - [Contains your Docker configurations and assets](/docs/deploystack/deploystack-configuration-directory.md)
14+
- `.deploystack/` directory - [Contains your Docker configurations and assets](/docs/deploystack/deploystack-configuration-directory)
1615
- `README.md` - For README.md updates
1716

1817
When changes are detected in these files, the app automatically triggers an update of your IaC templates in our [deploy-templates](https://github.com/deploystackio/deploy-templates) repository.
1918

20-
> [!IMPORTANT]
21-
> Changes are only processed when they occur on your repository's **default branch**. Modifications in other branches will not trigger template, logo, config or any other updates.
19+
<Callout type="warn">
20+
Changes are only processed when they occur on your repository's **default branch**. Modifications in other branches will not trigger template, logo, config or any other updates.
21+
</Callout>
2222

2323
## Installation
2424

@@ -47,12 +47,12 @@ When the app detects changes, it automatically updates:
4747
- Repository Homepage
4848
- Description
4949
- IaC templates
50-
- Depends on which technique (docker compose or docker run command) you choose, you can upload the `docker-compose.yml` or `docker-run.txt` in the `.deploystack` directory. Every time you update the files on your main branch (or additional branch), IaC templates will be updated automatically - [Automatic Updates](/docs/deploystack/deploystack-configuration-directory.md#automatic-updates).
50+
- Depends on which technique (docker compose or docker run command) you choose, you can upload the `docker-compose.yml` or `docker-run.txt` in the `.deploystack` directory. Every time you update the files on your main branch (or additional branch), IaC templates will be updated automatically - [Automatic Updates](/docs/deploystack/deploystack-configuration-directory#automatic-updates).
5151
- Environment variables
52-
- To make it easier for a user to deploy IaC templates, it is recommended to work with environment variables. For this purpose, you can upload an `env` file and add your appropriate variables - [Environment Variables](/docs/deploystack/deploystack-configuration-directory.md#environment-variables).
52+
- To make it easier for a user to deploy IaC templates, it is recommended to work with environment variables. For this purpose, you can upload an `env` file and add your appropriate variables - [Environment Variables](/docs/deploystack/deploystack-configuration-directory#environment-variables).
5353
- DeployStack Configuration
5454
- Project / Applicaton Logo
55-
- It is possible to upload your own logo to DeployStack catalog. To do this you need to upload a file to our directory `.deploystack`. Read more about it here: [Repository Logo](/docs/deploystack/deploystack-configuration-directory.md#repository-logo)
55+
- It is possible to upload your own logo to DeployStack catalog. To do this you need to upload a file to our directory `.deploystack`. Read more about it here: [Repository Logo](/docs/deploystack/deploystack-configuration-directory#repository-logo)
5656

5757
## Managing the Integration
5858

@@ -66,4 +66,4 @@ After installing the app:
6666
2. Commit and push your changes
6767
3. DeployStack will automatically update your deployment templates
6868

69-
For details about the `.deploystack` directory structure, check our [.deploystack Directory Reference](/docs/deploystack/deploystack-configuration-directory.md).
69+
For details about the `.deploystack` directory structure, check our [.deploystack Directory Reference](/docs/deploystack/deploystack-configuration-directory).

tmp/deploystack/iac-lifecycle.mdx renamed to docs/deploystack/iac-lifecycle.mdx

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
11
---
22
title: Infrastructure as Code Lifecycle
33
description: Guide to how DeployStack manages Infrastructure as Code template updates, including automatic synchronization, update triggers, and version control.
4-
menuTitle: Iac Lifecycle
54
---
65

76
# Infrastructure as Code Lifecycle
@@ -12,7 +11,7 @@ This guide explains how DeployStack manages and updates your Infrastructure as C
1211

1312
### Initial Setup
1413

15-
1. Create a `.deploystack` [configuration directory](/docs/deploystack/deploystack-configuration-directory.md) in your repository
14+
1. Create a `.deploystack` [configuration directory](/docs/deploystack/deploystack-configuration-directory) in your repository
1615
2. Add your Docker configuration files:
1716
- `docker-compose.yml` for Compose configurations
1817
- `docker-run.txt` for Docker run commands
@@ -21,7 +20,7 @@ This guide explains how DeployStack manages and updates your Infrastructure as C
2120

2221
### Enabling Automatic Updates
2322

24-
Install the [DeployStack Repository Sync](/docs/deploystack/github-application.md) GitHub App to keep your templates up to date when:
23+
Install the [DeployStack Repository Sync](/docs/deploystack/github-application) GitHub App to keep your templates up to date when:
2524

2625
- You modify Docker configurations in the `.deploystack` directory
2726
- Cloud providers update their IaC specifications
@@ -37,7 +36,7 @@ All IaC templates are stored in public and open-source repository: [https://gith
3736

3837
### Prerequisites for activating the flow
3938

40-
1. You have installed the [DeployStack GitHub app](/docs/deploystack/github-application.md).
39+
1. You have installed the [DeployStack GitHub app](/docs/deploystack/github-application).
4140
2. You have created the `.deploystack/docker-run.txt` or `.deploystack/docker-compose.yml` file.
4241

4342
The choice between `docker-run.txt` or `docker-compose.yml` depends on the submission process used to DeployStack. When submitting to DeployStack, you can choose two methods -> Docker Run or Docker Compose.
@@ -46,7 +45,7 @@ The choice between `docker-run.txt` or `docker-compose.yml` depends on the submi
4645

4746
Let's say you want to change your image tag from "deploystack/awesomeapp:v1" to "deploystack/awesomeapp:v2-next".
4847

49-
![DeployStack IaC Lifecycle](/docs/assets/images/deploystack/deploystack-iac-flow-via-github-app.webp)
48+
![DeployStack IaC Lifecycle](../assets/images/deploystack/deploystack-iac-flow-via-github-app.webp)
5049

5150
1. To do this, you will edit the file `.deploy stack/docker-run.txt` and change your new docker tag
5251
2. GitHub will send an event to the DeployStack backend with the change of the file `.deploy stack/docker-run.txt` because you have the DeployStack GitHub app installed.

tmp/deploystack/multiple-branches.mdx renamed to docs/deploystack/multiple-branches.mdx

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
11
---
22
title: Branch Strategy
33
description: Guide to implementing multi-branch deployment strategies with DeployStack, enabling version-specific deployments and automated template management.
4-
menuTitle: Branch Strategy
54
---
65

76
# Branch Strategy
@@ -21,7 +20,7 @@ Every repository starts with its default branch (typically `main` or `master`).
2120

2221
When you change your default branch in GitHub:
2322

24-
- DeployStack automatically detects the change - you need to install [DeployStack GitHub App](/docs/deploystack/github-application.md)
23+
- DeployStack automatically detects the change - you need to install [DeployStack GitHub App](/docs/deploystack/github-application)
2524
- Regenerates templates for the new default branch
2625
- Updates all deployment buttons
2726

@@ -81,7 +80,7 @@ This structure allows you to:
8180
- Modify service configurations independently
8281
- Keep each version's deployment parameters isolated
8382

84-
Remember: The DeployStack GitHub App only monitors the standard filenames: check [.deploystack Directory Reference for more info](/docs/deploystack/deploystack-configuration-directory.md)
83+
Remember: The DeployStack GitHub App only monitors the standard filenames: check [.deploystack Directory Reference for more info](/docs/deploystack/deploystack-configuration-directory)
8584

8685
## Real-World Example
8786

@@ -143,7 +142,7 @@ This strategy allows your users to:
143142
- Maximum of 5 active branches supported
144143
- Each branch can have unique Docker configurations
145144
- Default branch can be changed (switch to another branch and make it default) but not excluded
146-
- Branch configurations ([DeployStack config file](/docs/deploystack/deploystack-config-file.md)) must be in the default branch
145+
- Branch configurations ([DeployStack config file](/docs/deploystack/deploystack-config-file)) must be in the default branch
147146
- All branches are automatically monitored for changes
148147
- Template regeneration happens automatically when:
149148
- Branch content changes

0 commit comments

Comments
 (0)