Newer
Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
# GitLab CI/CD Setup for Federation Manager
This document explains how to set up and use the GitLab CI/CD pipeline for the Federation Manager project.
## Overview
The CI/CD pipeline includes a single stage with two different build jobs:
1. **Build (MR Validation)** - Builds Docker images for merge requests without pushing to registry
2. **Build and Push** - Builds Docker images and pushes them to the GitLab Container Registry for main branches
## Prerequisites
### GitLab Configuration
1. **Container Registry**: Ensure GitLab Container Registry is enabled for your project
2. **CI/CD Variables**: Configure the following variables in GitLab (Settings > CI/CD > Variables):
| Variable | Description | Required |
|----------|-------------|----------|
| `CI_REGISTRY` | GitLab Container Registry URL | Auto-provided |
| `CI_REGISTRY_USER` | Registry username | Auto-provided |
| `CI_REGISTRY_PASSWORD` | Registry password | Auto-provided |
### Repository Setup
1. Ensure your GitLab project has a Container Registry enabled
2. The pipeline uses the project's Container Registry by default
3. Docker images will be tagged with commit SHA and 'latest'
## Pipeline Stages
### Build Stage
The build stage contains two different jobs depending on the trigger:
#### MR Build (build-mr)
- **Trigger**: On merge requests
- **Actions**:
- Builds Docker image for validation
- Tags with local name: `federation-manager:$CI_COMMIT_SHORT_SHA`
- **Does NOT push to registry** (validation only)
- No registry authentication required
#### Build and Push (build-and-push)
- **Trigger**: On main, develop branches, and tags
- **Actions**:
- Builds Docker image
- Tags with commit SHA and 'latest'
- Pushes to GitLab Container Registry
- Requires registry authentication
## Docker Image Information
### Image Naming Convention
#### Registry Images (build-and-push job)
- Registry: `$CI_REGISTRY_IMAGE/federation-manager`
- Tags:
- `latest` - Latest build from main/develop branches
- `$CI_COMMIT_SHORT_SHA` - Specific commit hash
#### Local Images (build-mr job)
- Local name: `federation-manager:$CI_COMMIT_SHORT_SHA`
- **Note**: These images are built locally for validation only and are NOT pushed to the registry
### Base Image
- Python 3.12 official image
- Includes system dependencies: bash, build-essential, git, wget, iptables, etc.
- Exposes port 8989
- Runs with Gunicorn (4 workers)
## Usage
### Triggering Builds
1. **Automatic triggers**:
- **MR Build**: Create or update merge requests (builds for validation only)
- **Build and Push**: Push to main or develop branches, create tags
2. **Manual triggers**:
- Go to CI/CD > Pipelines in GitLab
- Click "Run Pipeline"
- Select branch/tag
### Build Types
#### Merge Request Validation
- **Purpose**: Validate that Docker builds work correctly before merging
- **Benefit**: Early feedback without affecting registry or consuming unnecessary resources
- **Output**: Local Docker image (not stored in registry)
- **Time**: Faster execution (no registry operations)
#### Production Builds
- **Purpose**: Create deployable images for main branches and releases
- **Output**: Images pushed to GitLab Container Registry
- **Accessibility**: Available for deployment and distribution
### Accessing Docker Images
**Note**: Only images from the `build-and-push` job are available in the registry. MR validation builds are local only.
1. **Pull from registry** (production images only):
```bash
docker login registry.gitlab.com
docker pull $CI_REGISTRY_IMAGE/federation-manager:latest
```
2. **Use in docker-compose**:
```yaml
services:
federation-manager:
image: registry.gitlab.com/your-group/federation-manager/federation-manager:latest
```
### Monitoring Pipeline
- **Pipeline status**: GitLab project > CI/CD > Pipelines
- **Job logs**: Click on individual jobs to view logs
- **Coverage reports**: Available in merge request widgets
- **Container registry**: GitLab project > Packages & Registries > Container Registry
## Troubleshooting
### Common Issues
1. **Docker build fails**:
- Check Dockerfile syntax
- Verify all required files are present
- Check .dockerignore doesn't exclude necessary files
2. **Registry push fails**:
- Verify Container Registry is enabled
- Check CI/CD variables are set correctly
- Ensure sufficient permissions
3. **Build fails**:
- Check Dockerfile syntax and build context
- Verify all required files are present and not excluded by .dockerignore
- Check Python 3.12 compatibility in requirements.txt
- Ensure base image availability