Add instructions.md

instructions.md

@@ -0,0 +1,89 @@
+# Configuring GitLab Domain for Correct URLs and Email Links
+
+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.
+
+---
+
+## Why setting external_url matters
+
+- 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.
+
+---
+
+## How to set the external_url in GitLab Docker
+
+### During Docker container launch
+
+Set the environment variable `GITLAB_OMNIBUS_CONFIG` with the external_url, e.g.:
+
+```
+docker run --env GITLAB_OMNIBUS_CONFIG="external_url 'https://gitlab.innovator.bh';" ...
+```
+
+Include this in your Docker run or Docker Compose configuration.
+
+---
+
+### Updating external_url after install
+
+1. Enter the GitLab container shell:
+
+```
+docker exec -it <gitlab-container-name> /bin/bash
+```
+
+2. Open the GitLab config file `/etc/gitlab/gitlab.rb` with your preferred editor and set:
+
+```
+external_url 'https://gitlab.innovator.bh'
+```
+
+3. Save the file and exit the editor.
+
+4. Run GitLab reconfiguration and restart:
+
+```
+gitlab-ctl reconfigure
+gitlab-ctl restart
+```
+
+---
+
+## Verification
+
+- 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).
+
+---
+
+## Notes
+
+- 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`.
+
+---
+
+## Troubleshooting
+
+- 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.
+
+---
+
+## Conclusion
+
+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_