Task #244
Updated by Sanghoon Lee 11 days ago
Install the bitname package for Redmine and configure Redmine to use as an external issue tracker for GitLab
<pre>
[GitLab] ──→ External Issue Tracker Setting ──→ [Bitnami Redmine:3000]
│
[MariaDB Container]
</pre>
-----------------------
h1. Redmine & GitLab Integration — Work Procedure
*Document Version:* 1.0
*Date:* 2026-03-24
*Environment:* Debian 13 (Trixie), Docker Compose v5.x, GitLab (Docker), Redmine (Docker)
---
h2. 1. Environment Overview
|_.Item|_.Details|
|Host OS|Debian 13 (Trixie)|
|Docker Compose|v5.0.2|
|GitLab URL|http://git.xela.com:8888|
|GitLab Host IP|192.168.1.102|
|Redmine URL|http://redmine.xela.com:3000|
|Redmine Host IP|192.168.1.102 (same host)|
|Redmine Image|redmine:6.1-trixie (Official Docker Image)|
|Database Image|mysql:8.0|
---
h2. 2. Architecture
<pre>
Client Browser
│
├── http://git.xela.com:8888 → GitLab Container (existing)
└── http://redmine.xela.com:3000 → Redmine Container (new)
│
MySQL Container
(redmine_db, internal only)
</pre>
---
h2. 3. Prerequisites
* Docker is already installed and running
* GitLab is already running as a Docker container on port 8888
* DNS or @/etc/hosts@ entries are configured for both domains
h3. 3.1 Verify Docker and Docker Compose
<pre>
docker --version
docker compose version
</pre>
---
h2. 4. Redmine Installation
h3. 4.1 Create Data Directories
<pre>
sudo mkdir -p /opt/redmine/redmine_data
sudo mkdir -p /opt/redmine/mysql_data
</pre>
h3. 4.2 Create Docker Compose File
<pre>
sudo nano /opt/redmine/docker-compose.yml
</pre>
Paste the following content:
<pre>
services:
redmine_db:
image: mysql:8.0
container_name: redmine_db
restart: always
environment:
MYSQL_ROOT_PASSWORD: root_secret # Change this
MYSQL_USER: redmine
MYSQL_PASSWORD: redmine_secret # Change this
MYSQL_DATABASE: redmine
volumes:
- /opt/redmine/mysql_data:/var/lib/mysql
networks:
- redmine_net
redmine:
image: redmine:6.1-trixie
container_name: redmine
restart: always
depends_on:
- redmine_db
ports:
- "192.168.1.102:3000:3000"
environment:
REDMINE_DB_MYSQL: redmine_db
REDMINE_DB_USERNAME: redmine
REDMINE_DB_PASSWORD: redmine_secret # Same as above
REDMINE_DB_DATABASE: redmine
REDMINE_SECRET_KEY_BASE: change_this_to_long_random_string # Change this
volumes:
- /opt/redmine/redmine_data:/usr/src/redmine/files
networks:
- redmine_net
networks:
redmine_net:
driver: bridge
</pre>
h3. 4.3 Start Containers
<pre>
cd /opt/redmine
docker compose up -d
</pre>
h3. 4.4 Verify Startup
<pre>
docker compose logs -f redmine
</pre>
Wait until the following message appears:
<pre>
* Listening on http://0.0.0.0:3000
</pre>
h3. 4.5 Verify Access
<pre>
curl -I http://192.168.1.102:3000
</pre>
Expected response: @HTTP/1.1 200 OK@
---
h2. 5. DNS / hosts Configuration
If an internal DNS server is not available, add the following entry to the @/etc/hosts@ file on *each client PC* that needs access.
*Linux / Mac:*
<pre>
sudo nano /etc/hosts
# Add the following line:
192.168.1.102 redmine.xela.com
</pre>
*Windows* (@C:\Windows\System32\drivers\etc\hosts@):
<pre>
192.168.1.102 redmine.xela.com
</pre>
{{warning(Note: @nslookup@ queries DNS directly and ignores @/etc/hosts@. Use @ping@ or @curl@ to verify that the hostname resolves correctly to @192.168.1.102@.)}}
---
h2. 6. Redmine Initial Configuration
h3. 6.1 Log in to Redmine
Open a browser and navigate to:
<pre>
http://redmine.xela.com:3000
</pre>
Default credentials:
* Username: @admin@
* Password: @admin@
{{warning(You will be prompted to change the password on first login.)}}
h3. 6.2 Enable REST API
<pre>
Administration → Settings → API tab
→ Check "Enable REST web service"
→ Save
</pre>
h3. 6.3 Create a Project
<pre>
Projects → New Project
→ Name: (your project name)
→ Identifier: (lowercase letters, numbers, hyphens only — e.g., xcp)
→ Save
</pre>
{{warning(Note the *Identifier* — it will be used in GitLab integration URL settings.)}}
h3. 6.4 Add User
!clipboard-202603241708-aqn9v.png!
---
h2. 7. GitLab Integration Setup
h3. 7.1 Allow Local Network Requests in GitLab
GitLab blocks requests to internal network addresses by default (SSRF protection).
This must be explicitly allowed.
<pre>
GitLab → Admin Area → Settings → Network
→ Outbound requests section
→ Check "Allow requests to the local network from webhooks and integrations"
→ In the allowlist input field, add:
192.168.1.102
redmine.xela.com
→ Save changes
</pre>
Direct URL:
<pre>
http://git.xela.com:8888/admin/application_settings/network
</pre>
h3. 7.2 Configure Redmine Integration (Admin Template)
<pre>
GitLab → Admin Area → Settings → Integrations → Redmine
→ Project URL: http://redmine.xela.com:3000/projects/:issues_tracker_id
→ Issue URL: http://redmine.xela.com:3000/issues/:id
→ New Issue URL: http://redmine.xela.com:3000/projects/:issues_tracker_id/issues/new
→ Save changes
</pre>
{{note(This sets the default template. Individual projects still need to be activated separately.)}}
h3. 7.3 Configure Redmine Integration per Project
For each GitLab project that should use Redmine:
<pre>
GitLab Project → Settings → Integrations → Redmine
→ Active: Checked
→ Project URL: http://redmine.xela.com:3000/projects/<redmine-project-identifier>
→ Issue URL: http://redmine.xela.com:3000/issues/:id
→ New Issue URL: http://redmine.xela.com:3000/projects/<redmine-project-identifier>/issues/new
→ Save changes
</pre>
{{note(Replace @<redmine-project-identifier>@ with the actual Redmine project identifier (e.g., @xcp@).)}}
h3. 7.4 Disable GitLab Internal Issue Tracker per Project
<pre>
GitLab Project → Settings → General
→ Visibility, project features, permissions (expand)
→ Issues (or Work items) toggle → OFF
→ Save changes
</pre>
---
h2. 8. Verification & Testing
h3. 8.1 Verify Redmine Menu in GitLab
<pre>
GitLab Project → Left sidebar
→ Plan → Redmine
→ Confirm that it redirects to:
http://redmine.xela.com:3000/projects/<redmine-project-identifier>
</pre>
h3. 8.2 Verify Issue Link in Commit Message
*Step 1.* Create a test issue in Redmine:
<pre>
Redmine → Project → Issues → New Issue
→ Subject: "Test Issue"
→ Submit
→ Note the issue number (e.g., #1)
</pre>
*Step 2.* Create a test commit with the Redmine issue URL in the message:
<pre>
echo "redmine integration test" > test.txt
git add test.txt
git commit -m "Integration test - http://redmine.xela.com:3000/issues/1"
git push origin <branch-name>
</pre>
*Step 3.* Verify the link in GitLab:
<pre>
GitLab Project → Code → Commits
→ Click on the test commit
→ Confirm that the Redmine URL in the commit message is a clickable link
→ Click the link and confirm it opens:
http://redmine.xela.com:3000/issues/1
</pre>
h3. 8.3 Verification Checklist
|_.#|_.Test Item|_.Expected Result|_.Pass/Fail|
|1|Access http://redmine.xela.com:3000|Redmine login page displayed|[ ]|
|2|GitLab → Plan → Redmine menu visible|Menu item appears in sidebar|[ ]|
|3|Click Plan → Redmine|Redirects to Redmine project page|[ ]|
|4|Commit message with Redmine URL|URL appears as clickable link|[ ]|
|5|Click Redmine URL in commit|Opens correct Redmine issue page|[ ]|
|6|GitLab internal Issues menu|Not visible (disabled)|[ ]|
---
h2. 9. Container Management
*Start Redmine*
<pre>
cd /opt/redmine
docker compose up -d
</pre>
*Stop Redmine*
<pre>
cd /opt/redmine
docker compose down
</pre>
*View Logs*
<pre>
docker compose logs -f redmine # Redmine logs
docker compose logs -f redmine_db # MySQL logs
</pre>
*Restart Redmine only*
<pre>
docker compose restart redmine
</pre>
---
h2. 10. Notes & Limitations
|_.Item|_.Details|
|Issue sync direction|One-way only: GitLab commit messages link to Redmine issues|
|Two-way sync|Not supported natively. Requires additional plugins|
|Commit message format|Include full Redmine issue URL (e.g., @http://redmine.xela.com:3000/issues/1@)|
|@#id@ shorthand|Does not link to Redmine — links to GitLab internal issues instead|
|Protected branches|Direct push to @main@ may be blocked — use feature branches|
|Per-project setup|Redmine integration and Issues toggle must be configured per GitLab project|
---
_End of Document_