Wi-Fi Guest Portal

This project is a voucher code captive portal for UniFi networks.

Installation

Requirements

To run the captive portal, you will need:

• A UniFi controller
• A webserver reachable from the guest network
• Docker installed on the webserver

Deploying with Docker

1. Pull the latest Docker image from Docker Hub:

   docker pull carlgo11/guest-portal

2. Create a .env file with the following environment variables:
3. Run the Docker container, mounting the .env file:

   docker run -d \
   -p 80:3000 \
   --env-file .env \
   carlgo11/guest-portal

4. Access the captive portal through the webserver's URL.

Deploying with Docker Compose

1. Create a .env file with the environment variables found under Configuration.
2. Create a docker-compose.yml file with the following data:

   version: '3.8'
   services:
     redis:
       image: redis:alpine
       volumes:
         - redis:/data
     node:
       image: carlgo11/guest-portal
       ports:
         - 3001:3000
       env_file: .env
   
   volumes:
     redis:

Creating background images (Optional)

By default, the captive portal fetches the Bing Image of the Day to use as the background. If you prefer to use your own background images, follow these steps:

Seasonal backgrounds

The captive portal can display use different backgrounds depending on the season. If you wish to use this, follow these steps:

1. Create a new directory with the following subdirectories:

   • Spring
   • Summer
   • Autumn
   • Winter

2. Place your desired background images inside these folders. The client will automatically select the appropriate background image based on the browser window resolution.

3. Specify which hemisphere you're in (north or south) in the .env file. This is necessary to calculate the current season accurately.

4. Link the parent directory of your custom background images to /app/public/img/backgrounds/ in the Docker container. If using docker, you can link the directory by adding the following line to the docker command:

      docker run -d \
      -p 80:3000 \
      --env-file .env \
   +  -v $(pwd)/backgrounds:/app/public/img/backgrounds \
      carlgo11/guest-portal

   If using Docker Compose, link the directory by adding the following lines to docker-compose.yml:

     version: '3.8'
     services:
       redis:
         image: redis:alpine
         volumes:
           - redis:/data
       node:
         image: carlgo11/guest-portal
   +      volumes:
   +      - ./backgrounds:/app/public/img/background
         ports:
           - 3001:3000
         env_file: .env
   
     volumes:
       redis:

Static backgrounds

1. Create a new directory and place your desired background images inside this directory. The client will automatically select the appropriate background image based on the browser window resolution.

2. Link the directory containing your background images to /app/public/img/backgrounds/ in the Docker container. If using the Docker CLI, you can link the directory by adding the following line to the docker command:

      docker run -d \
      -p 80:3000 \
      --env-file .env \
   +  -v $(pwd)/backgrounds:/app/public/img/backgrounds \
      carlgo11/guest-portal

Configuration

The captive portal can be configured using the following environment variables:

Variable	Description	Default Value
HEMISPHERE	Hemisphere setting for seasonal background selection
IMG_PATH	Path to background images	img/background
ORIGIN	Origin URL for WebAuthn	http://localhost:3000
UNIFI_HOST	UniFi controller host IP address
UNIFI_PORT	UniFi controller port	443
UNIFI_TLS	Enable TLS for UniFi controller	false
UNIFI_USERNAME	Username for UniFi controller authentication
UNIFI_PASSWORD	Password for UniFi controller authentication
UNIFI_SITE	UniFi site name	default
UNIFI_SSID	WLAN SSID name
REDIS_HOST	Redis server host	redis
REDIS_PORT	Redis server port	6379

Usage

1. Users connect to the guest Wi-Fi network.
2. They are redirected to the captive portal login page.
3. Users enter the voucher code provided by the administrator.
4. Upon successful authentication, users are granted access to the internet.