148 lines
5.5 KiB
Markdown
148 lines
5.5 KiB
Markdown
# 🚀 Deploy to Docker (Swarm or Compose) Action
|
|
|
|
Robustly deploy your Docker Compose files to Docker Swarm or regular Docker Compose environments via SSH. This action provides detailed debug output, secure SSH handling, validation, and automatic cleanup for a smooth, reliable deployment experience.
|
|
|
|
---
|
|
|
|
## ✨ Features
|
|
|
|
- ✅ **Supports both Docker Swarm and Docker Compose**
|
|
- 🔑 **Secure SSH key handling**
|
|
- 🔍 **Remote validation of Docker Compose files**
|
|
- 🧹 **Automatic cleanup of temporary files**
|
|
- 📋 **Detailed debug logs for easy troubleshooting**
|
|
- 📂 **Optional copying of Docker build context**
|
|
- 📄 **Optional copying of `.env` files**
|
|
|
|
---
|
|
|
|
## 📥 Inputs
|
|
|
|
| Input | Description | Required | Default |
|
|
|-----------------------|----------------------------------------------------------------|----------|------------------|
|
|
| `stack_name` | Docker stack or compose project name | ✅ Yes | - |
|
|
| `ssh_host` | SSH host | ✅ Yes | - |
|
|
| `ssh_user` | SSH username | ✅ Yes | - |
|
|
| `ssh_key` | SSH private key | ✅ Yes | - |
|
|
| `deploy_file` | Path to the processed deployment file | ✅ Yes | - |
|
|
| `deploy_mode` | Deployment mode: `swarm` or `compose` | ❌ No | `swarm` |
|
|
| `remote_temp_dir` | Remote temporary directory for deployment files | ❌ No | `/tmp` |
|
|
| `copy_build_context` | Whether to copy Docker build context to remote host | ❌ No | `false` |
|
|
| `build_context_path` | Local path to Docker build context | ❌ No | `build-context` |
|
|
| `copy_env_file` | Whether to copy `.env` file to remote host | ❌ No | `false` |
|
|
| `env_file_path` | Local path to `.env` file | ❌ No | `.env` |
|
|
| `docker_registry` | Docker registry URL (defaults to Docker Hub if empty) | ❌ No | - |
|
|
| `docker_username` | Docker registry username | ❌ No | - |
|
|
| `docker_password` | Docker registry password or token | ❌ No | - |
|
|
|
|
---
|
|
|
|
## 🚦 Deployment Modes
|
|
|
|
This action supports two deployment modes:
|
|
|
|
- **Docker Swarm (`swarm`)** 🚢
|
|
Deploys using `docker stack deploy`.
|
|
|
|
- **Docker Compose (`compose`)** 🐳
|
|
Deploys using `docker compose up`.
|
|
|
|
---
|
|
|
|
## 🛠️ Example Usage
|
|
|
|
### Deploying to Docker Swarm 🚢
|
|
|
|
```yaml
|
|
- name: Deploy to Docker Swarm 🚢
|
|
uses: your-org/deploy-to-docker-action@main
|
|
with:
|
|
stack_name: my-awesome-stack
|
|
ssh_host: ${{ vars.SSH_HOST }}
|
|
ssh_user: ${{ secrets.SSH_USER }}
|
|
ssh_key: ${{ secrets.SSH_KEY }}
|
|
deploy_file: docker-compose.processed.yml
|
|
deploy_mode: swarm
|
|
```
|
|
|
|
### Deploying with Docker Compose 🐳 (including build context and `.env` file)
|
|
|
|
```yaml
|
|
- name: Deploy using Docker Compose 🐳
|
|
uses: your-org/deploy-to-docker-action@main
|
|
with:
|
|
stack_name: my-compose-project
|
|
ssh_host: ${{ vars.SSH_HOST }}
|
|
ssh_user: ${{ secrets.SSH_USER }}
|
|
ssh_key: ${{ secrets.SSH_KEY }}
|
|
deploy_file: docker-compose.processed.yml
|
|
deploy_mode: compose
|
|
copy_build_context: true
|
|
build_context_path: ./docker-context
|
|
copy_env_file: true
|
|
env_file_path: ./production.env
|
|
```
|
|
|
|
### Deploying with Private Registry Authentication 🔐
|
|
|
|
```yaml
|
|
- name: Deploy with Private Registry 🔐
|
|
uses: your-org/deploy-to-docker-action@main
|
|
with:
|
|
stack_name: my-private-stack
|
|
ssh_host: ${{ vars.SSH_HOST }}
|
|
ssh_user: ${{ secrets.SSH_USER }}
|
|
ssh_key: ${{ secrets.SSH_KEY }}
|
|
deploy_file: docker-compose.yml
|
|
docker_registry: ghcr.io
|
|
docker_username: ${{ github.actor }}
|
|
docker_password: ${{ secrets.GITHUB_TOKEN }}
|
|
```
|
|
|
|
---
|
|
|
|
## 🧑💻 How It Works
|
|
|
|
This action performs the following steps:
|
|
|
|
1. 🔑 **Securely creates a temporary SSH key file** for authentication.
|
|
2. 📁 **Creates a secure temporary directory** on the remote host.
|
|
3. 🔐 **Optionally performs Docker login** on the remote host if credentials are provided.
|
|
4. 📤 **Copies your processed Docker Compose file** to the remote host.
|
|
4. 📂 **Optionally copies Docker build context** to the remote host.
|
|
5. 📄 **Optionally copies `.env` file** to the remote host.
|
|
6. 🔍 **Validates the Docker Compose file remotely** to ensure correctness.
|
|
7. 🚢🐳 **Deploys your stack/project** based on the selected deployment mode.
|
|
8. 🧹 **Cleans up temporary files** both locally and remotely.
|
|
|
|
---
|
|
|
|
## 📖 Debugging & Logs
|
|
|
|
During deployment, the action provides detailed debug logs at every step, making it easy to troubleshoot any issues:
|
|
|
|
- ✅ SSH connection details
|
|
- ✅ File transfer status
|
|
- ✅ Validation results
|
|
- ✅ Deployment status
|
|
- ✅ Cleanup confirmation
|
|
|
|
---
|
|
|
|
## ⚠️ Requirements
|
|
|
|
- SSH access to your Docker host.
|
|
- Docker & Docker Compose installed on the remote host.
|
|
- Proper permissions to deploy stacks or compose projects remotely.
|
|
|
|
---
|
|
|
|
## 📜 License
|
|
|
|
This action is open-source software licensed under the MIT license.
|
|
|
|
---
|
|
|
|
Happy deploying! 🎉
|
|
|
|
— **Grand** |