init

README.md

@@ -0,0 +1,91 @@
+# 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}`