Update instructions.md

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.
+Welcome! This guide helps you install and configure GitLab in a Docker container inside your Proxmox LXC environment in an easy and friendly way. 🐳💻
-
-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
+## 📋 Prerequisites
 
-- GitLab uses the value of `external_url` to generate **absolute URLs** for links in emails and UI.
+- Proxmox LXC container with Linux OS (Ubuntu/Debian recommended).
-- Setting an accessible, fully qualified domain name or IP address here ensures users receive correct URLs.
+- Network access to the container and ability to run `sudo`.
-- If you don't set this correctly, emails will contain URLs like `http://localhost` which break user workflows.
+- 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.
+- To watch GitLab logs live:
-- The links in the email should contain your configured domain (https://gitlab.innovator.bh).
+
+```
+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.
+- [x] Installed Docker and GitLab container
-- If using HTTPS, ensure your SSL/TLS certificates are correctly configured.
+- [x] Configured SMTP email with your credentials
-- For changes to take effect, always run `gitlab-ctl reconfigure`.
+- [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.
+- [GitLab Official Docs](https://docs.gitlab.com/)
-- Check logs inside the container for errors during reconfigure: `docker logs -f <container>`
+- [Docker Official Docs](https://docs.docker.com/)
-- Verify firewall and network allow access to the domain and ports.
 
 ---
 
-## 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 support or questions, please reach out to the project maintainer.
-
-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_