GNS3 Server Docker Image

A Docker image for running GNS3 server with optional Tailscale integration, based on the official GNS3 remote installation script.

Features

• Official GNS3 Installation - Uses the official GNS3 remote installation script
• Ubuntu 22.04 Base - Stable and well-supported base image
• Optional Tailscale Integration - Connect your GNS3 server to your Tailscale network
• Complete GNS3 Setup - Includes QEMU, Docker, VirtualBox support, and IOU
• Persistent Storage - Volume mounts for projects, images, and configs
• Health Checks - Built-in health monitoring

Quick Start

Basic Usage (No Tailscale)

# Using Docker
docker run -d \
  --name gns3-server \
  --privileged \
  -p 3080:3080 \
  -v gns3-projects:/opt/gns3/projects \
  -v gns3-images:/opt/gns3/images \
  your-registry/gns3-server:latest

# Using Docker Compose
docker-compose up -d

With Tailscale Integration

docker run -d \
  --name gns3-server \
  --privileged \
  --cap-add=NET_ADMIN \
  --cap-add=SYS_MODULE \
  --device=/dev/net/tun:/dev/net/tun \
  --device=/dev/kvm:/dev/kvm \
  -p 3080:3080 \
  -v gns3-projects:/opt/gns3/projects \
  -v gns3-images:/opt/gns3/images \
  -e ENABLE_TAILSCALE=true \
  -e TAILSCALE_AUTHKEY=your-auth-key \
  -e TAILSCALE_HOSTNAME=gns3-server \
  your-registry/gns3-server:latest

Environment Variables

Variable	Default	Description
ENABLE_TAILSCALE	false	Enable Tailscale integration
TAILSCALE_AUTHKEY	""	Tailscale authentication key
TAILSCALE_HOSTNAME	""	Custom hostname for Tailscale node
GNS3_CONFIG_FILE	/etc/gns3/gns3_server.conf	Path to GNS3 configuration file

Volume Mounts

Path	Description
/opt/gns3/projects	GNS3 project files
/opt/gns3/images	VM/container images (QEMU, Docker, etc.)
/opt/gns3/configs	Additional configuration files
/etc/gns3	GNS3 server configuration

Ports

Port	Description
3080	GNS3 server REST API and WebSocket

Required Capabilities

GNS3 server requires several capabilities to function properly:

• --privileged - Simplest option for full access
• Or specific capabilities:
  • --cap-add=NET_ADMIN - Network management
  • --cap-add=SYS_MODULE - Kernel module loading
  • --cap-add=SYS_ADMIN - System administration

Device Access

• /dev/net/tun:/dev/net/tun - TUN/TAP networking
• /dev/kvm:/dev/kvm - Hardware acceleration (if available)

Image Details

• Base: Ubuntu 22.04 LTS
• Size: ~1.5GB (includes full GNS3 stack)
• GNS3 Version: 2.2.54 (latest stable)
• Includes:
  • GNS3 Server
  • QEMU system emulation
  • Docker support
  • VirtualBox integration
  • IOU support (32-bit compatibility)
  • uBridge networking
  • VPCS
  • Dynamips (Cisco router emulation)
  • Tailscale (latest stable)

Tailscale Setup

1. Get an auth key from your Tailscale admin console:

   • Go to Tailscale Admin Console
   • Generate a new auth key
   • Optionally set it to be reusable and/or ephemeral

2. Run with Tailscale enabled:

   docker run -d \
     --name gns3-server \
     --privileged \
     -e ENABLE_TAILSCALE=true \
     -e TAILSCALE_AUTHKEY=tskey-auth-xxx \
     -e TAILSCALE_HOSTNAME=gns3-lab \
     gns3-server:latest
   

3. Access via Tailscale:

   • The server will be accessible on your Tailscale network
   • Use the Tailscale IP or hostname to connect
   • Default port is still 3080

Development and Building

Local Build

# Build the image
docker build -t gns3-server .

# Multi-platform build (if using buildx)
docker buildx build --platform linux/amd64,linux/arm64 -t gns3-server .

Testing

# Test basic functionality
docker run --rm --privileged -p 3080:3080 gns3-server

# Test with Tailscale (requires auth key)
docker run --rm --privileged \
  -e ENABLE_TAILSCALE=true \
  -e TAILSCALE_AUTHKEY=your-key \
  gns3-server

# Check health
curl http://localhost:3080/v2/version

CI/CD Workflows

This repository includes automated workflows:

Workflows

1. On Commit to Main

   • Trigger: Commits to main branch (excludes tags)
   • Purpose: Builds and publishes development images

2. On Tag Push

   • Trigger: New tag creation
   • Purpose: Builds and publishes release images tagged as latest

Prerequisites

Configure these secrets in your repository:

• OCI_TOKEN: OCI registry authentication token
• OCI_USER: OCI registry username

Docker Compose Examples

Basic Setup

version: '3.8'
services:
  gns3-server:
    image: your-registry/gns3-server:latest
    container_name: gns3-server
    restart: unless-stopped
    privileged: true
    ports:
      - "3080:3080"
    volumes:
      - gns3-projects:/opt/gns3/projects
      - gns3-images:/opt/gns3/images
    environment:
      - ENABLE_TAILSCALE=false

volumes:
  gns3-projects:
  gns3-images:

With Tailscale

version: '3.8'
services:
  gns3-server:
    image: your-registry/gns3-server:latest
    container_name: gns3-server
    restart: unless-stopped
    privileged: true
    ports:
      - "3080:3080"
    volumes:
      - gns3-projects:/opt/gns3/projects
      - gns3-images:/opt/gns3/images
    environment:
      - ENABLE_TAILSCALE=true
      - TAILSCALE_AUTHKEY=${TAILSCALE_AUTHKEY}
      - TAILSCALE_HOSTNAME=gns3-lab

volumes:
  gns3-projects:
  gns3-images:

Troubleshooting

Common Issues

1. Permission denied on volumes

   # Fix volume permissions
   docker run --rm -v gns3-projects:/data alpine chown -R 1000:1000 /data
   

2. Tailscale authentication fails

   • Verify auth key is valid and not expired
   • Ensure container has --privileged or required capabilities
   • Check Tailscale admin console for device status

3. Health check failures

   • Check if GNS3 server is starting: docker logs <container>
   • Verify port 3080 is accessible
   • Ensure sufficient resources (RAM, CPU)

4. QEMU/KVM not working

   • Ensure /dev/kvm is available on host
   • Check if host supports hardware virtualization
   • Try running with --device=/dev/kvm:/dev/kvm

Logs

# View container logs
docker logs gns3-server

# Follow logs in real-time
docker logs -f gns3-server

# Check Tailscale status (if enabled)
docker exec gns3-server tailscale status

Performance Tips

1. Use hardware acceleration: Mount /dev/kvm if available
2. Allocate sufficient resources: At least 2GB RAM, 2+ CPU cores
3. Use SSD storage: For better I/O performance with VM images
4. Monitor resource usage: Check CPU and memory consumption

Security Considerations

• Privileged containers: Required for networking and device access
• Network isolation: Use Tailscale for secure remote access
• File permissions: Ensure proper ownership of mounted volumes
• Updates: Regularly update the image for security patches

License

This project is licensed under the MIT License. See the LICENSE file for details.

Support

For GNS3-specific issues, refer to the official GNS3 documentation. For container-specific issues, please open an issue in this repository.