Skip to content

Commit ecb19ab

Browse files
LasimLasim
authored
Merge pull request #89 from deploystackio/feat/getting-started
feat(started): update getting started
2 parents 92bdb43 + 84b8b4a commit ecb19ab

File tree

1 file changed

+152
-74
lines changed

1 file changed

+152
-74
lines changed

‎docs/deploystack/getting-started.md

Lines changed: 152 additions & 74 deletions
Original file line numberDiff line numberDiff line change
@@ -4,112 +4,190 @@ description: Start deploying Docker applications across cloud providers with Dep
44

55
# Getting Started with DeployStack
66

7-
Let's get your Docker project deployed across different cloud platforms with minimal effort.
7+
DeployStack offers two distinct paths to transform your Docker projects into cloud-ready deployments: a Quick Start path for immediate results, and our Recommended path for enhanced control and automation. Let's explore both approaches in detail.
88

9-
## What is DeployStack?
9+
## Understanding the Two Paths
1010

11-
DeployStack transforms your Docker configurations into cloud-ready infrastructure templates. Whether you're using Docker run commands or docker-compose.yml files, we help make your project easily deployable by others.
11+
### 🚀 Quick Start Path
1212

13-
What makes it powerful is the one-click deployment feature - your users can deploy your project instantly on their preferred cloud platform using the provider's native deployment capabilities.
13+
The Quick Start path is designed for developers who want to immediately make their Docker projects deployable, with minimal setup required. This approach works with your existing repository structure.
1414

15-
## Project Requirements
15+
### Recommended Path
1616

17-
### Repository Requirements
17+
The Recommended path provides additional features through a `.deploystack` configuration directory and GitHub app integration. This approach enables automatic updates, environment variable management, and project customization.
1818

19-
- A public GitHub repository (private repositories aren't supported yet)
20-
- Either a docker-compose.yml file or documented Docker run commands
21-
- Container images must be pre-built and available in a supported registry
19+
## Quick Start Path: Detailed Guide
2220

23-
### Container Requirements
21+
### For Docker Compose Projects
2422

25-
For docker-compose.yml:
23+
#### Requirements
2624

27-
- Must use the `image` directive (no build instructions)
28-
- Images must be from supported registries
29-
- No private images currently supported
25+
- A public GitHub repository
26+
- A `docker-compose.yml` or `docker-compose.yaml` file in your repository's root directory
27+
- Container images must be:
28+
- Pre-built and available in supported registries
29+
- Publicly accessible
30+
- Referenced using the `image` directive
3031

31-
For Docker run commands:
32+
#### Step-by-Step Process
3233

33-
- Must be complete, runnable commands
34-
- Can include standard Docker options (ports, volumes, environment variables)
35-
- Images must be publicly accessible
34+
1. **Repository Preparation**
35+
- Ensure your `docker-compose.yml` is in the root directory
36+
- Verify all images are publicly accessible
37+
- Check that your compose file uses supported configuration options
3638

37-
## Generating Your First Templates
39+
2. **Submission**
40+
- Visit [deploystack.io/submit](https://deploystack.io/submit){:target="_blank"}
41+
- Enter your GitHub repository URL
42+
- Our system automatically detects your compose file
43+
- Review the detected configuration
3844

39-
1. Visit [deploystack.io/submit](https://deploystack.io/submit)
40-
2. Submit your GitHub repository URL
41-
3. We'll detect your Docker configurations and generate infrastructure templates
42-
4. Your project gets added to our catalog at [deploystack.io/c](https://deploystack.io/c)
45+
3. **Template Generation**
46+
- Infrastructure templates are generated for each supported cloud provider
47+
- Templates are stored in our public repository
48+
- You receive deployment button code for your README.md
4349

44-
We support multiple cloud providers including AWS CloudFormation, DigitalOcean, and Render.com. See our complete list of supported providers in the [docker-to-iac documentation](/docs/docker-to-iac/index.md).
50+
### For Docker Run Commands
4551

46-
## Configuration Examples
52+
#### Requirements
4753

48-
### Using docker-compose.yml
54+
- A public GitHub repository
55+
- A valid Docker run command that includes:
56+
- Image name and tag
57+
- Port mappings (if required)
58+
- Environment variables (if needed)
59+
- Volume mounts (if necessary)
4960

50-
```yaml
51-
version: '3'
52-
services:
53-
web:
54-
image: nginx:alpine
55-
ports:
56-
- "80:80"
57-
cache:
58-
image: redis:latest
59-
ports:
60-
- "6379:6379"
61-
```
61+
#### Step-by-Step Process
62+
63+
1. **Command Preparation**
64+
- Ensure your Docker run command is complete and valid
65+
- Verify all referenced images are publicly available
66+
- Test the command locally if possible
67+
68+
2. **Submission**
69+
- Visit [deploystack.io/submit](https://deploystack.io/submit){:target="_blank"}
70+
- Enter your GitHub repository URL
71+
- Paste your Docker run command
72+
- Review the parsed configuration
73+
74+
3. **Template Generation**
75+
- Infrastructure templates are generated automatically
76+
- Templates are optimized for each cloud provider
77+
- You receive deployment button code
6278

63-
### Using Docker Run Commands
79+
## Recommended Path: Comprehensive Setup
80+
81+
### The `.deploystack` Directory Structure
82+
83+
Create a `.deploystack` directory in your repository with these components:
6484

6585
```bash
66-
# Web Server
67-
docker run -d \
68-
-p 80:80 \
69-
--name web \
70-
nginx:alpine
71-
72-
# Cache Server
73-
docker run -d \
74-
-p 6379:6379 \
75-
--name cache \
76-
redis:latest
86+
.deploystack/
87+
├── docker-compose.yml # Your Docker Compose configuration
88+
├── docker-run.txt # Or your Docker run command
89+
├── .env # Environment variables (optional)
90+
└── logo.webp # Your project logo (optional)
7791
```
7892

79-
Both configurations will be translated into appropriate infrastructure templates for your chosen cloud providers.
93+
#### Component Details
8094

81-
## Adding Deployment Buttons
95+
**Docker Configuration Files**:
8296

83-
After template generation:
97+
- `docker-compose.yml`: Your complete Docker Compose configuration
98+
- `docker-run.txt`: Alternative to compose file, contains your Docker run command
99+
- Only one of these files should be present
100+
101+
For more configuration options please check our [.deploystack Directory Reference](/docs/deploystack/deploystack-configuration-directory.md).
102+
103+
### GitHub App Integration
104+
105+
The [DeployStack Repository Sync](https://github.com/apps/deploystack-repository-sync){:target="_blank"} app enables:
106+
107+
1. **Automatic Updates**
108+
- Monitors changes to your Docker configurations
109+
- Updates templates when configurations change
110+
- Ensures templates stay in sync with your project
111+
112+
2. **Installation Steps**
113+
- Visit the GitHub app installation page
114+
- Select your repositories
115+
- Configure access permissions
116+
- Verify installation
117+
118+
3. **Monitoring and Updates**
119+
- Changes to `.deploystack` directory trigger updates
120+
- Only default branch changes are processed
121+
- Templates are automatically regenerated
122+
123+
## Behind the Scenes: How It Works
84124

85-
1. Visit [deploystack.io/deploy-button](https://deploystack.io/deploy-button)
86-
2. Generate deployment button code
87-
3. Add the buttons to your README.md
125+
### The docker-to-iac Module
88126

89-
Users can then deploy your project with a single click on their preferred cloud platform.
127+
Our open-source [docker-to-iac](https://github.com/deploystackio/docker-to-iac){:target="_blank"} module:
90128

91-
## Next Steps
129+
- Parses your Docker configurations
130+
- Handles multiple cloud provider translations
131+
- Supports various infrastructure patterns
132+
- Maintains provider-specific optimizations
92133

93-
1. Review the [Configuration Requirements](/docs/deploystack/docker-compose-requirements.md)
94-
2. Learn about [One-Click Deploy](/docs/deploystack/one-click-deploy.md)
95-
3. Check [Supported Registries](/docs/docker-to-iac/supported-registries.md)
134+
### Template Generation Process
135+
136+
1. **Configuration Analysis**
137+
- Docker configurations are parsed
138+
- Dependencies are identified
139+
140+
2. **Provider-Specific Translation**
141+
- Templates generated for each provider
142+
- Provider best practices applied
143+
- Resource mappings optimized
144+
145+
3. **Template Storage**
146+
- Templates stored in [deploy-templates](https://github.com/deploystackio/deploy-templates){:target="_blank"}
147+
- Version controlled for tracking
148+
- Publicly accessible
149+
150+
### Deployment Button Integration
151+
152+
After template generation:
153+
154+
1. Visit [deploystack.io/deploy-button](https://deploystack.io/deploy-button){:target="_blank"}
155+
2. Select your preferred button style
156+
3. Copy the generated code
157+
4. Add to your README.md
96158

97159
## Best Practices
98160

99-
- Store configuration files in your repository's root directory
100-
- Use specific version tags for images rather than `latest`
101-
- Ensure all images are publicly accessible
102-
- Test configurations locally before submitting
103-
- Document any specific requirements or environment variables
161+
### Repository Organization
162+
163+
- Keep Docker configurations clean and well-documented
164+
- Use specific version tags for images
165+
- Document environment variable requirements
166+
- Include clear deployment instructions
167+
168+
### Configuration Management
169+
170+
- Use the `.deploystack` directory for better organization
171+
- Keep environment variables separate
172+
- Test configurations locally
173+
174+
### Deployment Strategy
175+
176+
- Start with the Quick Start path if needed
177+
- Migrate to Recommended path for better control
178+
- Use GitHub app for automatic updates
179+
180+
## Troubleshooting Common Issues
104181

105-
## Need Help?
182+
### Template Generation
106183

107-
- Review our [Troubleshooting Guide](/docs/deploystack/troubleshooting.md)
108-
- Join our [Discord Community](https://discord.gg/UjFWwByB)
184+
- Verify image accessibility
185+
- Check Docker configuration syntax
186+
- Ensure all required ports are exposed
187+
- Validate environment variables
109188

110-
## Limitations
189+
## Need Additional Help?
111190

112-
- Only supports public repositories currently
113-
- Requires pre-built container images
114-
- No support for private image registries
115-
- Build instructions not supported (use pre-built images)
191+
- Review our detailed [Troubleshooting Guide](/docs/deploystack/troubleshooting.md)
192+
- Join our active [Discord Community](https://discord.gg/UjFWwByB){:target="_blank"}
193+
- Submit issues on GitHub to our [Feedback repository](https://github.com/deploystackio/feedback){:target="_blank"}

0 commit comments

Comments
 (0)