Skip to content

Carlgo11/guest-portal

Repository files navigation

Wi-Fi Guest Portal

CC-BY-4.0 GitHub Packages Docker Hub

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.