Local network binding

• gdk.test is the standard hostname for referring to the local GDK instance.
• registry.test is the standard hostname for referring to a local container registry.

We recommend mapping these to a loopback interface because it’s more flexible, but they can also be mapped to 127.0.0.1.

Local interface

To set up gdk.test and registry.test as hostnames using 127.0.0.1:

1. Add the following to the end of /etc/hosts (you must use sudo to save the changes):

   127.0.0.1 gdk.test registry.test

2. Set hostname to gdk.test:

   gdk config set hostname gdk.test

3. Reconfigure GDK:

   gdk reconfigure

4. Restart GDK to use the new configuration:

   gdk restart

Create loopback interface

Some functionality may not work if GDK processes listen on localhost or 127.0.0.1 (for example, services running under Docker). Therefore, an IP address on a different private network should be used.

172.16.123.1 is a useful private network address that can avoid clashes with localhost and 127.0.0.1.

To set up gdk.test and registry.test as hostnames using 172.16.123.1:

1. Create an internal interface.

   For macOS, create an alias to the loopback adapter:

   sudo ifconfig lo0 alias 172.16.123.1

   For Linux, create a dummy interface:

   sudo ip link add dummy0 type dummy
   sudo ip address add 172.16.123.1 dev dummy0
   sudo ip link set dummy0 up

2. Add the following to the end of /etc/hosts (you must use sudo to save the changes):

   172.16.123.1 gdk.test registry.test

Make sure you remove previous entries for gdk.test, otherwise the hosts file will respect the first entry.

1. Set hostname to gdk.test:

   gdk config set hostname gdk.test

2. Set listen_address to 172.16.123.1:

   gdk config set listen_address 172.16.123.1

3. Reconfigure GDK:

   gdk reconfigure

4. Restart GDK to use the new configuration:

   gdk restart

5. Optional. Make the loopback alias persist across reboots.

Create loopback device on startup

For the loopback alias to work across reboots, the aliased IP address must be setup upon system boot.

macOS

To automate this on macOS, create a file called org.gitlab1.ifconfig.plist at /Library/LaunchDaemons/ containing:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>org.gitlab1.ifconfig</string>
    <key>RunAtLoad</key>
    <true/>
    <key>Nice</key>
    <integer>10</integer>
    <key>ProgramArguments</key>
    <array>
      <string>/sbin/ifconfig</string>
      <string>lo0</string>
      <string>alias</string>
      <string>172.16.123.1</string>
    </array>
</dict>
</plist>

Ensure the created file has the correct permissions:

sudo chown root:wheel /Library/LaunchDaemons/org.gitlab1.ifconfig.plist
sudo chmod 644 /Library/LaunchDaemons/org.gitlab1.ifconfig.plist

Linux

The method to persist this dummy interface on Linux varies between distributions.

Ubuntu

On Ubuntu, you can run:

sudo nmcli connection add type dummy ifname dummy0 ip4 172.16.123.1

Access GDK on private IP address

You can access the GDK server through your computer’s private IP address. Use this method when you test on multiple devices on the same IP range or network.

Find your local IP address (Mac or Linux)

From a terminal, run the following command:

# On macOS or Linux systems with net-tools installed
ifconfig -a

# On macOS using the default ethernet port or WiFi
# ethernet use `en1`. WiFi use `en0`.
ipconfig getifaddr en0

# On modern Linux systems where ifconfig is unavailable
ip addr

The command provides a list of all wired and wireless adapters that are available on your computer. Look for the entry with status: active and note its inet address (like 192.168.1.100). If you know your network’s IP range, you can find your IP address by typing the following command on your terminal:

# If your IP range is 192.168.xxx.xxx
ifconfig -a | grep 192.168

The command output displays your local IP address:

inet 192.168.1.100 netmask 0xffffff00 broadcast 192.168.1.255

Update configuration files

1. Update gdk.yml:

   listen_address: 192.168.1.100  # Replace with your actual IP address

2. Reconfigure GDK:

   gdk reconfigure

3. Test for IP address connectivity:

   # Should print your IP address and port when server starts
   gdk start

Map your local IP address to gdk.test

To set up gdk.test and registry.test as hostnames by using your local IP address:

1. Add the following to the end of /etc/hosts (you must use sudo to save the changes):

   192.168.1.100 gdk.test registry.test  # Replace 192.168.1.100 with your actual IP address

2. Set hostname to gdk.test:

   gdk config set hostname gdk.test

3. Reconfigure GDK:

   gdk reconfigure

4. Test gdk.test connectivity:

   # Should print gdk.test and port when server starts
   gdk restart

Troubleshooting

• If your router’s dynamic host configuration protocol (DHCP) assigned your computer’s IP address, you might need to update your configuration files if you change internet connections. This issue can happen if you switch from ethernet to a Wi-Fi connection. It can also happen if your router assigns a new IP address because your lease expired.
• If you try to load GDK by using the IP address from a Windows PC, check that your internet connection is set to private. Only make this change if your PC is fully updated, and you are on a trusted network.
• If you can load your GDK instance by IP address but stylesheets, images, and scripts don’t load, check the Network tab of your browser for 404 errors. You might need to update your local /etc/hosts file to match the GDK host’s file configuration.