Documentation

JEspresso works with Ubiquiti Unifi controller versions 4.X and early 5.X (it doesn't support Dream Machine and last APIs yet). You can install it on small systems like Raspberry Pi (I suggest Pi 4+ with external database, so you can reduce sd write damage), or any Docker supported host (Server or NAS).

Run as standalone application (fastest)

You can download a ready-runnable application from here and run application by jespresso.sh script or manually typing

# java -jar ./jespresso.jar

For configuration, you need to application.properties files, as described in configuration paragraph.

Building runnable JAR from sources

1) You can start installing Maven, a Git client and OpenJdk (I used AdoptOpenJdk)

2) clone JEspresso repository on your local hard drive using git:


            # git clone https://github.com/emanuelepaiano/jespresso-lite.git

3) move to sources directory and run mvnw for binary building:


            # cd jEspresso-lite
# ./mvnw clean package -DskipTests

all dependencies will be downloaded (it takes a while), and you should find jar file into target/ directory, all dependencies will be copied into target/libs directory.

Building a docker container

You can run JEspresso using a Docker container on each docker-enabled devices (i.e. NAS or Server).

Inside source directory, there is docker-compose subdirectory: this constains several yaml database profile (mysql, postgres and in-memory H2).

1) Install docker and docker-compose on your host and compile JEspresso from sources with previous described steps.

2) Move into docker compose directory


             
# cd jEspresso-lite/docker-compose

3) Edit env files into env/ directory, setting parameters like Unifi controller credentials.

4) Run (as poweruser) docker-compose with 'up' parameter and yaml file:


            # docker-compose -f jespresso-be-DATABASE_PLATFORM.yml up

replacing DATABASE_PLATFORM with your favourite platform database (i.e. for MYSQL use jespresso-be-mysql.yml file).

NB: omitting -f parameter, docker-compose will uses default file jespresso-be-h2-inmemory.yml .

5) After running you should see messages like


            .................. omitted verbose logs ...............................

Tomcat started on port(s): 8080 (http) with context path ''
Started JEspressoApplication in 16.364 seconds (JVM running for 17.251)

without errors, this means your Captive Portal is running and ready.

Configuration

The configuration depends on the type of setup chosen in the previous steps.

If you have installed Unifi controller and jEspresso on same host, and you don't want to store data permanently, you can run application with default options (anyway I suggest to change security parameters). With default options, JEspresso uses embedded H2 in-memory database, so if you reboot the application, you will lose the data.

After Guest Portal Unifi setup, you can login into admin panel using these credentials:

url: http://localhost:8080/admin/
user: administrator@localhost
password: password

If you want to use different database (i.e. MySql or PostgreSql) you should have a custom configuration.

Custom configuration (advanced)

For the standard setup just edit the application.properties file, while for setup via docker, you need to edit the env files before run docker-compose.

Setting Unifi Controller parameters

Unifi controller starts on TCP 8443 port by default. If you installed controller on jespresso's same host, you need only to edit user, password and sitename.

Into application.properties you should edit variables directly or setting environment vars (i.e. CONTROLLER_URL)


              # UNIFI CONTROLLER SETTINGS
unifiApi.controller.url=${CONTROLLER_URL:https://localhost:8443/}
unifiApi.controller.username=${CONTROLLER_USER:admin}
unifiApi.controller.password=${CONTROLLER_PASSWORD:password}
unifiApi.controller.sitename=${CONTROLLER_SITENAME:default}

if the environment variables, those to the left of the ':' character, are not set, they will assume the values to the right of that character (i.e. admin for CONTROLLER_USER).

Into docker environment files you should edit environment vars


              CONTROLLER_URL=https://localhost:8443/
CONTROLLER_USER=admin
CONTROLLER_PASSWORD=password
CONTROLLER_SITENAME=default

Setting Wifi guests sessions parameters

Editing these parameters, you can reduce connection time and/or blocking navigation:

Into application.properties you should edit variables directly or setting environment vars (i.e. CONTROLLER_URL)


              # session duration (in minutes)
unifiApi.controller.session.duration=${SESSION_DURATION:90}

# hide duration minutes to user (extra time for emergency). I.e. duration is 90 and hiddenMinutes is 30, 
# users see 90 - 30 = 60 minutes as remaing times
unifiApi.controller.session.hiddenMinutes=${SESSION_HIDDEN_MINUTES:0}

# session blocked after expire (i.e. blockMinutes=300 means "a guest cannot connect for 300/60=5 hours")
unifiApi.controller.session.blockMinutes=${SESSION_BLOCK_MINUTES:300}

# max download speed (in Kbps)
unifiApi.controller.session.downloadSpeed=${DOWNLOAD_SPEED:2048}

# max upload speed (in Kbps)
unifiApi.controller.session.uploadSpeed=${UPLOAD_SPEED:640}

# max quota (in Mbytes)
unifiApi.controller.session.quota=${QUOTA:4096}

Into docker environment files you should edit environment vars


              SESSION_DURATION=60
SESSION_HIDDEN_MINUTES=0
SESSION_BLOCK_MINUTES=300
DOWNLOAD_SPEED=2048
UPLOAD_SPEED=640
QUOTA=4096

Setting database parameters

Into application.properties you should edit variables directly or setting environment vars (i.e. DATASOURCE_USER)


              # -----------------
# PostgreSQL setup
# -----------------
spring.datasource.url=${DATASOURCE_URL:jdbc:postgresql://localhost:5432/jespresso}
spring.datasource.username=${DATASOURCE_USER:postgres}
spring.datasource.password=${DATASOURCE_PASSWORD:password}
spring.datasource.driverClassName=${DATASOURCE_DRIVER_CLASSNAME:org.postgresql.Driver}
spring.jpa.database-platform=${DATASOURCE_HIBERNATE_DIALECT:org.hibernate.dialect.PostgreSQLDialect}
#spring.datasource.schema=classpath:/scripts/postgresql/schema.sql
spring.jpa.hibernate.ddl-auto=${DATASOURCE_DDL_AUTO:update}

Into docker environment files you should edit environment vars


              DATASOURCE_URL=jdbc:postgresql://localhost:5432/jespresso
DATASOURCE_HIBERNATE_DIALECT=org.hibernate.dialect.PostgreSQLDialect
DATASOURCE_USER=postgres
DATASOURCE_PASSWORD=password
DATASOURCE_DRIVER_CLASSNAME=org.postgresql.Driver
DATASOURCE_DDL_AUTO=none
DATASOURCE_SCHEMA=classpath:/scripts/postgresql/schema.sql
#DATASOURCE_DATA=classpath:/scripts/postgresql/data.sql

Setting security parameters

Into application.properties you should replace JWT_SECRET and JWT_EXPIRATION default values with your secret values:


          # -- JWT and Security Settings --
jwt.header: ${JWT_HEADER:X-Auth} 
jwt.secret: ${JWT_SECRET:mySecret}
jwt.expiration: ${JWT_EXPIRATION:7200}

Don't forget to change default login passwords from Admin Frontend.

Setting advanced parameters (only for developers!)

Into application.properties you can edit variables directly or setting environment vars


              # simulate Unifi Controller (useful for developers), set it to false in production 
unifiApi.controller.mock=${UNIFI_MOCK:false}

Setting UNIFI_MOCK to true you will enable Unifi Controller simulation so, if you are running jespresso on localhost and Captive's sitename is 'default', you can test portal opening your browser to

http://localhost/guest/s/default/?ap=accesspoint_address&id=mac_address

without having a real Unifi Access point.

Building custom landing page

When a client connects to Access Point, it will be redirected automatically to path


                          /guest/s/default/?ap=ACCESS_POINT_MAC&id=CLIENT_MAC

on your jEspresso. Your webpage should get query params:

ap: current access point's mac address
id: current guest client's mac address

So you need only to do a POST REST request to /api/authorize-guest, sending a body like


            {
  "acceptTou": "true",
  "accessPointMacAddress": "FF:FF:FF:FF:FF:FF",
  "browser": "Firefox",
  "email": "john@doe.com",
  "ipAddress": "10.0.0.253",
  "macAddress": "FF:FF:FF:FF:FF:F3",
  "operatingSystem": "Linux"
}

Not all fields are mandatory, you need only

acceptTou: it must be true, Tou is Terms Of Use
accessPointMacAddress: it must be equal to ACCESS_POINT_MAC value
macAddress: it must be equal to CLIENT_MAC value

Other values will be detected by backend automatically. If all fields are good, you will receive a REST response 200 with body

{
  "response": 200,
  "description": "200 OK",
  "payload": {
    "macAddress": "FF:FF:FF:FF:FF:F3",
    "minutesLeft": 59,
    "secondsLeft": 59,
    "expireOn": "2020-09-02 17:16:46",
    "lastLogin": "2020-09-02 16:16:46",
    "valid": true
  }
}

otherwise you will receive a 400 REST response. If valid parameter equal to true, this means your client is connected for 59 minutes and 59 seconds, otherwise client session is expired.

Using Angular/React or JQuery, you can write your own webpage, and save them into src/main/resources/static/landing folder and recompile the application.

License

This basic version is released under Apache2 License. Custom/commercials version will be released with different licenses.

Donate

If you like this project, consider a little donation, so I can buy new hardware for testing and development. At least you can offer me a coffee.. :)