When deploying GitLab, the default HTTP port 80 might conflict with other services or violate organizational security policies. The proper way to modify this involves multiple configuration layers.

The authoritative approach is through GitLab's main configuration file:

# /etc/gitlab/gitlab.rb
external_url 'http://yourdomain.com:8888'
nginx['listen_port'] = 8888

After making these changes, apply them with:

sudo gitlab-ctl reconfigure
sudo gitlab-ctl restart

Many administrators miss these critical aspects:

• The external_url must explicitly include the port number
• NGINX configuration needs separate port declaration
• Firewall rules must be updated

To verify the change worked:

sudo netstat -tulnp | grep nginx
# Should show nginx listening on your custom port

For reverse proxy setups or SSL termination, additional configuration is needed:

# For HTTPS setups
external_url 'https://yourdomain.com:8443'
nginx['ssl_listen_port'] = 8443
nginx['redirect_http_to_https'] = true

If the port isn't changing:

1. Check for syntax errors in gitlab.rb
2. Verify no other services occupy the target port
3. Examine logs: sudo gitlab-ctl tail nginx

When attempting to modify GitLab's default HTTP port (80) to a custom port like 8888, many administrators encounter persistent configuration issues where the service continues running on port 80 despite making changes. This happens because modern GitLab installations require multiple coordinated configuration changes.

The primary configuration file that controls GitLab's web interface is /etc/gitlab/gitlab.rb. However, several other components need attention:

# Main configuration file
/etc/gitlab/gitlab.rb

# NGINX configuration (derived from gitlab.rb)
/var/opt/gitlab/nginx/conf/gitlab-http.conf

# Rails configuration
/var/opt/gitlab/gitlab-rails/etc/gitlab.yml

Here's the definitive way to change the port:

# Edit the main configuration
external_url "http://gitlab.example.com:8888"
nginx['listen_port'] = 8888
nginx['listen_https'] = false

# For Docker installations add:
gitlab_rails['gitlab_shell_ssh_port'] = 8888

After making these changes, run:

sudo gitlab-ctl reconfigure
sudo gitlab-ctl restart

Confirm the changes took effect:

# Check NGINX configuration
sudo grep -r "listen 8888" /var/opt/gitlab/nginx/conf/

# Verify running ports
sudo netstat -tulnp | grep gitlab

SELinux conflicts: On RHEL/CentOS systems:

sudo semanage port -a -t http_port_t -p tcp 8888

Firewall issues:

sudo firewall-cmd --permanent --add-port=8888/tcp
sudo firewall-cmd --reload

Proxy configurations: If using a reverse proxy, ensure it forwards requests to the correct port.

For Docker deployments, use environment variables:

docker run --detach \
  --hostname gitlab.example.com \
  --publish 8888:8888 \
  --env GITLAB_OMNIBUS_CONFIG="external_url 'http://gitlab.example.com:8888/'; nginx['listen_port'] = 8888;" \
  gitlab/gitlab-ce:latest