# 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}`