92 lines
2.4 KiB
Markdown
92 lines
2.4 KiB
Markdown
# Jenkins Docker Deploy Example
|
||
|
||
Example repository demonstrating a Jenkins pipeline that:
|
||
|
||
1. **Builds** a Docker image
|
||
2. **Pushes** the image to a container registry (Docker Hub, etc.)
|
||
3. **SSHs** to a deployment machine
|
||
4. **Clones** (or pulls) this repo to get `docker-compose.yml`
|
||
5. **Deploys** with `docker compose up -d`
|
||
|
||
## Repository Structure
|
||
|
||
```
|
||
.
|
||
├── Jenkinsfile # Pipeline definition
|
||
├── Dockerfile # Application image
|
||
├── docker-compose.yml # Deployment compose (pulled by deploy host)
|
||
├── app.py # Minimal Python web app
|
||
└── README.md
|
||
```
|
||
|
||
## Prerequisites
|
||
|
||
### Jenkins
|
||
|
||
- **Docker** installed and Jenkins user in `docker` group
|
||
- **Pipeline** and **SSH Agent** plugins
|
||
- **Git** for cloning
|
||
|
||
### Jenkins Credentials
|
||
|
||
Create these in **Manage Jenkins → Credentials**:
|
||
|
||
| ID | Type | Purpose |
|
||
|----|------|---------|
|
||
| `docker-registry-credentials` | Username/Password | Docker Hub or registry login |
|
||
| `deploy-ssh-key` | SSH Username with private key | SSH to deploy host |
|
||
|
||
### Deploy Host
|
||
|
||
- Docker and Docker Compose installed
|
||
- SSH access for the deploy user
|
||
- If using a **private registry**: run `docker login` on the deploy host (or add to the pipeline)
|
||
|
||
## Configuration
|
||
|
||
Edit the `environment` block in `Jenkinsfile`:
|
||
|
||
```groovy
|
||
environment {
|
||
DOCKER_REGISTRY = 'docker.io' // or your registry (ghcr.io, etc.)
|
||
DOCKER_IMAGE = 'myorg/myapp' // e.g., username/repo
|
||
DEPLOY_HOST = 'deploy-server.example.com'
|
||
DEPLOY_USER = 'deploy'
|
||
DEPLOY_PATH = '/opt/myapp' // Where to clone & run compose
|
||
GIT_REPO_URL = 'https://github.com/myorg/jenkins-docker-deploy-example.git'
|
||
}
|
||
```
|
||
|
||
## Pipeline Stages
|
||
|
||
1. **Build** – `docker build` with tag from branch (e.g. `latest` for main, `123-abc1234` for others)
|
||
2. **Push** – `docker push` to registry using stored credentials
|
||
3. **Deploy** – SSH to host, clone/pull repo, run `docker compose up -d`
|
||
|
||
## First-Time Deploy Host Setup
|
||
|
||
On the deploy host:
|
||
|
||
```bash
|
||
# Create deploy directory
|
||
sudo mkdir -p /opt/myapp
|
||
sudo chown deploy:deploy /opt/myapp
|
||
|
||
# Ensure deploy user can run docker (add to docker group)
|
||
sudo usermod -aG docker deploy
|
||
```
|
||
|
||
## Manual Test
|
||
|
||
```bash
|
||
# Build and run locally
|
||
docker build -t myapp:test .
|
||
docker run -p 8080:8080 myapp:test
|
||
# Visit http://localhost:8080
|
||
```
|
||
|
||
## Branch Behavior
|
||
|
||
- **main** → image tag `latest`
|
||
- **other branches** → image tag `{BUILD_NUMBER}-{GIT_SHA}`
|