Docker

An official GoNetSim Docker image is available on the GitHub Container Registry at lachlanharrisdev/gonetsim. The image is built from the main branch of the GoNetSim repository, and is automatically updated with each new commit to main. It is available for both amd64 and arm64 architectures.

Benefits

Using the Docker image is the preferred method of running GoNetSim if you require long periods of uptime, or none of the pre-built binaries are compatible with your system. This includes macOS users, as support for standalone macOS binaries are experimental and do not support notarization.

Versions

The latest tag of the image will point to the latest semver release. This is recommended for most users, as releases are more thoroughly tested and stable than the main branch directly.

If you want bleeding edge features or fixes, you can use the nightly tag. nightly points to the latest build of the main branch, or you can choose a specific nightly build with the nightly-YYYYMMDD tag. nightly builds are done every 24 hours at 2am UTC if new changes have been committed to main.

Setup

Docker standalone

1. Install Docker on your system if you haven’t already. You can find instructions for your platform on the Docker website.

2. Pull the latest GoNetSim image from the GitHub Container Registry:

   docker pull ghcr.io/lachlanharrisdev/gonetsim:latest

3. Run the GoNetSim container:

   docker run --rm \
       -p 53:53/udp -p 53:53/tcp \
       -p 80:80 -p 443:443 \
       -p 25:25 -p 465:465 \
       ghcr.io/lachlanharrisdev/gonetsim:latest

Docker Compose

1. Install Docker & Docker Compose on your system if you haven’t already. You can find instructions for your platform on the Docker website.

2. Copy the following docker-compose.yml file to your system:

   services:
       gonetsim:
           image: ghcr.io/lachlanharrisdev/gonetsim:latest
   
           # publish the default (non-privileged) ports
           # to publish standard ports on the host instead, swap to:
           #  - "53:53/udp"
           #  - "53:53/tcp"
           #  - "80:80"
           #  - "443:443"
           #  - "25:25"
           #  - "465:465"
           ports:
           - "53:53/udp"
           - "53:53/tcp"
           - "80:80"
           - "443:443"
           - "25:25"
           - "465:465"
   
           # by default GoNetSim will generate a config file on first run
           # If you want to pin the config to /etc/gonetsim/gonetsim.toml, mount it there:
           # volumes:
           #   - ../gonetsim.toml:/etc/gonetsim/gonetsim.toml:ro

3. Start the container with Docker Compose:

   docker-compose up -d

From source

In some scenarios it may be desirable to build the Docker image from source, such as when testing changes to the image or if you want to use a specific branch or commit of the GoNetSim repository.

Requirements

• Ko installed on your system. You can install it with the following command:

  go install github.com/google/ko@v0.18.1

1. Clone the GoNetSim repository:

   git clone https://github.com/lachlanharrisdev/gonetsim.git

2. Navigate to the repository directory:

   cd gonetsim

3. Build the Docker image:

   go install github.com/google/ko@v0.18.1
   KO_DOCKER_REPO=gonetsim ko build --local --bare --tags=local .

4. Run the GoNetSim container:

   docker run --rm \
       -p 53:53/udp -p 53:53/tcp \
       -p 80:80 -p 443:443 \
       -p 25:25 -p 465:465 \
       gonetsim:local

Usage

The container behaves very similar to the standalone binary.

On first start, if no config file is found, GoNetSim will generate a default commented config file (using the embedded default_config.toml).

By default it will use the same search paths as the standalone binary. If you mount a config file at /etc/gonetsim/gonetsim.toml, it will be used.

To use a custom configuration, mount a file over this path with the -v flag in docker run:

docker run --rm \
    -p 53:53/udp -p 53:53/tcp \
    -p 80:80 -p 443:443 \
    -p 25:25 -p 465:465 \
    -v /path/to/config.toml:/etc/gonetsim/gonetsim.toml:ro \
    ghcr.io/lachlanharrisdev/gonetsim:latest

The services will be available at the same ports as the standalone binary, and can be accessed in the same way. To test this, you can use the dig command for DNS:

dig @localhost -p 53 example.com

Or curl for HTTP:

curl -k -v https://localhost:443