Update instructions.md
This commit is contained in:
parent
87b9213c1e
commit
3e9daa3cb5
144
instructions.md
144
instructions.md
@ -1,89 +1,151 @@
|
||||
# Configuring GitLab Domain for Correct URLs and Email Links
|
||||
# 🚀 GitLab Docker Installation and Configuration Guide
|
||||
|
||||
When using GitLab in a Docker container, GitLab generates URLs used in its web UI and emails (such as user account approval, notifications, password reset) based on the **external_url** setting.
|
||||
|
||||
If your GitLab emails or web UI links show `http://localhost` or another incorrect domain, it is usually because the **external_url** is not set correctly.
|
||||
Welcome! This guide helps you install and configure GitLab in a Docker container inside your Proxmox LXC environment in an easy and friendly way. 🐳💻
|
||||
|
||||
---
|
||||
|
||||
## Why setting external_url matters
|
||||
## 📋 Prerequisites
|
||||
|
||||
- GitLab uses the value of `external_url` to generate **absolute URLs** for links in emails and UI.
|
||||
- Setting an accessible, fully qualified domain name or IP address here ensures users receive correct URLs.
|
||||
- If you don't set this correctly, emails will contain URLs like `http://localhost` which break user workflows.
|
||||
- Proxmox LXC container with Linux OS (Ubuntu/Debian recommended).
|
||||
- Network access to the container and ability to run `sudo`.
|
||||
- SMTP email credentials for sending notifications.
|
||||
- A preferred domain name (e.g. `gitlab.innovator.bh`) pointing to your server.
|
||||
|
||||
---
|
||||
|
||||
## How to set the external_url in GitLab Docker
|
||||
## 🛠 Installation Steps
|
||||
|
||||
### During Docker container launch
|
||||
### 1. Run the interactive install script
|
||||
|
||||
Set the environment variable `GITLAB_OMNIBUS_CONFIG` with the external_url, e.g.:
|
||||
Run this command inside your container terminal:
|
||||
|
||||
```
|
||||
docker run --env GITLAB_OMNIBUS_CONFIG="external_url 'https://gitlab.innovator.bh';" ...
|
||||
curl -sSL https://your-server/path/install_gitlab.sh | sudo bash
|
||||
```
|
||||
|
||||
Include this in your Docker run or Docker Compose configuration.
|
||||
You'll be prompted to enter:
|
||||
|
||||
- Your container's IP (for info only)
|
||||
- Admin email
|
||||
- SMTP email and password
|
||||
- SMTP server address and port
|
||||
- Initial root admin password
|
||||
|
||||
---
|
||||
|
||||
### Updating external_url after install
|
||||
### 2. Wait for the installation to complete
|
||||
|
||||
1. Enter the GitLab container shell:
|
||||
The script will:
|
||||
|
||||
- Install Docker and dependencies ⚙️
|
||||
- Create persistent directories 📂
|
||||
- Pull and launch GitLab Docker container 🐙
|
||||
- Configure SMTP email settings ✉️
|
||||
- Set the admin password you provided 🔐
|
||||
|
||||
You'll see your admin login details printed at the end.
|
||||
|
||||
---
|
||||
|
||||
## 🌐 Accessing GitLab
|
||||
|
||||
Open your browser and go to:
|
||||
|
||||
```
|
||||
docker exec -it <gitlab-container-name> /bin/bash
|
||||
http://<your-container-ip>
|
||||
```
|
||||
|
||||
2. Open the GitLab config file `/etc/gitlab/gitlab.rb` with your preferred editor and set:
|
||||
Log in as:
|
||||
|
||||
- Username: `root`
|
||||
- Password: (the password you entered during install)
|
||||
|
||||
---
|
||||
|
||||
## ✍️ Editing `/etc/gitlab/gitlab.rb`
|
||||
|
||||
If you need to update settings like the domain URL (external_url):
|
||||
|
||||
### Option A: Use nano editor inside the container
|
||||
|
||||
Nano is pre-installed during installation. Use it like this:
|
||||
|
||||
```
|
||||
sudo docker exec -it gitlab bash
|
||||
nano /etc/gitlab/gitlab.rb
|
||||
```
|
||||
|
||||
Update the line starting with:
|
||||
|
||||
```
|
||||
external_url 'http://localhost'
|
||||
```
|
||||
|
||||
To your actual domain:
|
||||
|
||||
```
|
||||
external_url 'https://gitlab.innovator.bh'
|
||||
```
|
||||
|
||||
3. Save the file and exit the editor.
|
||||
Save with `Ctrl+O`, exit with `Ctrl+X`.
|
||||
|
||||
4. Run GitLab reconfiguration and restart:
|
||||
Then run:
|
||||
|
||||
```
|
||||
gitlab-ctl reconfigure
|
||||
gitlab-ctl restart
|
||||
```
|
||||
|
||||
to apply changes.
|
||||
|
||||
---
|
||||
|
||||
### Option B: Edit on host and copy back
|
||||
|
||||
If you prefer, you can edit the file on your host and copy it into the container:
|
||||
|
||||
```
|
||||
docker cp gitlab:/etc/gitlab/gitlab.rb ./gitlab.rb
|
||||
nano ./gitlab.rb
|
||||
docker cp ./gitlab.rb gitlab:/etc/gitlab/gitlab.rb
|
||||
docker exec -it gitlab gitlab-ctl reconfigure
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Verification
|
||||
## 🛠 Troubleshooting
|
||||
|
||||
- After updating and restarting GitLab, send a test email or perform an action that triggers email notifications.
|
||||
- The links in the email should contain your configured domain (https://gitlab.innovator.bh).
|
||||
- To watch GitLab logs live:
|
||||
|
||||
```
|
||||
sudo docker logs -f gitlab
|
||||
```
|
||||
|
||||
- Reset root password if needed:
|
||||
|
||||
```
|
||||
sudo docker exec -it gitlab gitlab-rails runner "user = User.where(id: 1).first; user.password = 'NEWPASS'; user.password_confirmation = 'NEWPASS'; user.save!"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
## ✅ Summary Checklist
|
||||
|
||||
- Make sure your domain (gitlab.innovator.bh) is DNS resolvable and points to your GitLab server IP.
|
||||
- If using HTTPS, ensure your SSL/TLS certificates are correctly configured.
|
||||
- For changes to take effect, always run `gitlab-ctl reconfigure`.
|
||||
- [x] Installed Docker and GitLab container
|
||||
- [x] Configured SMTP email with your credentials
|
||||
- [x] Set initial root password
|
||||
- [x] Nano text editor installed inside container for easy editing
|
||||
- [x] Instructions provided for editing important config (`external_url`)
|
||||
- [x] Encouraged secure password practices and password reset options
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
## 📚 Additional References
|
||||
|
||||
- If you still see localhost URLs, double-check your `external_url` setting.
|
||||
- Check logs inside the container for errors during reconfigure: `docker logs -f <container>`
|
||||
- Verify firewall and network allow access to the domain and ports.
|
||||
- [GitLab Official Docs](https://docs.gitlab.com/)
|
||||
- [Docker Official Docs](https://docs.docker.com/)
|
||||
|
||||
---
|
||||
|
||||
## Conclusion
|
||||
Thank you for choosing this GitLab Docker installer! 🎉
|
||||
|
||||
Setting the correct `external_url` to your real domain in GitLab Docker is essential for proper URLs in emails and UI.
|
||||
|
||||
For more details, see the official docs:
|
||||
|
||||
[GitLab Docker External URL Configuration](https://docs.gitlab.com/install/docker/configuration/#configure-the-external-url)
|
||||
|
||||
---
|
||||
|
||||
_Last updated: September 2025_
|
||||
For support or questions, please reach out to the project maintainer.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user