Skip to content
Zeus Server: Self-order Point of Sale solution, powered by the Lightning Network
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
backend Adjust default price of products Jun 1, 2019
doc Add margin to header May 26, 2019
frontend Bugfix and optimisations for beer tap May 28, 2019
gradle Split frontend and backend Feb 5, 2019
.editorconfig Initial commit for open sourced version, removed all merchant specifi… Sep 21, 2018
.gitattributes Initial commit for open sourced version, removed all merchant specifi… Sep 21, 2018
.gitignore Add functionality from EnergyKitchen Feb 5, 2019
.huskyrc Fix management endpoints, update frontend dependencies May 14, 2019
.prettierignore Fix management endpoints, update frontend dependencies May 14, 2019
.prettierrc Initial commit for open sourced version, removed all merchant specifi… Sep 21, 2018
.travis.yml Fix Travis script May 14, 2019
Jenkinsfile Initial commit for open sourced version, removed all merchant specifi… Sep 21, 2018
LICENSE Initial commit for open sourced version, removed all merchant specifi… Sep 21, 2018
README.md Add more screenshots and URLs to modules May 16, 2019
build.gradle Split frontend and backend Feb 5, 2019
docker-compose.yml Update README to document the docker-compose quick start May 13, 2019
gradle.properties Update Spring Boot dependencies, enable prometheus May 13, 2019
gradlew Initial commit for open sourced version, removed all merchant specifi… Sep 21, 2018
gradlew.bat Initial commit for open sourced version, removed all merchant specifi… Sep 21, 2018
settings.gradle Split frontend and backend Feb 5, 2019

README.md

Zeus Server

Zeus Server is a Lightning Network Point of Sale application for LND, written in Java.

If you are looking for the Mobile App, please visit ZeusLN/zeus.

screenshot webshop

Quick Start / How to Use

This chapter will show you how you can quickly start Zeus Server.

You will need:

  • Your own LND node (see next chapter)
  • docker and docker-compose installed on your machine

Set up your own LND node

The Spring Boot backend uses the LightningJ Java library to connect to a Lightning Network Daemon (LND) over gRPC. You will need to set up an LND node with version 0.6.1-beta or newer.

There are many tutorials out there but we recommend either this (default) or this (docker)

This application is network agnostic, so it does not matter if you are running testnet or mainnet. But of course we strongly recommend to start with testnet first!

After the LND node is running and is fully synced to the chain, follow the steps below. We assume that LND saves its files to ~/.lnd/. If you changed that path, adjust the following example paths accordingly.

  • Make sure the gRPC port (default 10009) of the node is open and reachable
  • Copy the file ~/.lnd/tls.cert to the folder src/main/resources/certs and also name it tls.cert
  • Get the hex value of the invoice.macaroon and store it somewhere, we'll need this later.
    Use this command for example:
    xxd -p -c 999 ~/.lnd/data/chain/bitcoin/testnet/invoice.macaroon
  • Get the hex value of the readonly.macaroon and store it somewhere, we'll need this later.
    Use this command for example:
    xxd -p -c 999 ~/.lnd/data/chain/bitcoin/testnet/readonly.macaroon

Configure application

Now you need to configure the application to use the LND node you just set up.

To do this, edit the file application-dev.yml in the folder backend/src/main/resources/config and change the following values:

application:
    bitcoin:
        # point this to http://<bitcoind-hostname>:8332/rest/chaininfo.json if you have a full node.
        # set it to 'disabled' if you don't have a bitcoind full node running.
        restUrl: disabled
    mail:
        send: true
        recipient: mail@example.com
    lnd:
        host: localhost
        port: 10009
        certPath: classpath:/certs/tls.cert
        # insert the hex values of the macaroon obtained in the previous step here!
        invoiceMacaroonHex: 0201036c.....
        readonlyMacaroonHex: 0201036c.....

The most important thing you need to change is to change the hostname/port and to add the hex values for the macaroons that you saved somewhere in the previous step.

Start with docker-compose

This will start the docker images from Docker Hub and mount the configuration file:

docker-compose up

Now you should see the application when opening http://localhost:9000/ in your browser.

Start development env

To start developing you need to start every component manually:

  1. Start DB in background: docker-compose up -d zeus-db
  2. Start the backend: cd backend; ../gradlew bootRun
  3. Start the frontend: cd frontend; yarn install; yarn start

Now you should see the application when opening http://localhost:9000/ in your browser.

Available modules

The following modules have been implemented so far:

Web Shop

A classic web shop with a shopping cart and a checkout procedure.

URL: http://host:port/#/shop

screenshot webshop screenshot webshop checkout

Self service

A self-order page that only displays a certain number of products that can be ordered by directly paying an invoice that is shown. Available for portrait or landscape display orientation.

URL: http://host:port#/self-service/INVOICE-PREFIX

screenshot self service portrait

URL: http://host:port/#/self-service-landscape/INVOICE-PREFIX

screenshot self service landscape

Donation

A simple donation form that can be embedded as an iframe for example.

URL: http://host:port/#/donate/DONATION-TEXT

screenshot donation

Administrative interface

Apart from the default JHipster admin pages for health, metrics, configuration and log configuration, there are also two specific interfaces related to the Lightning Network.

URL: http://host:port/#/admin

The default username is admin and the password is admin.

Invoice overview

A list of all paid and unpaid invoices, can be filtered by type and date.

screenshot admin invoices

Node and channel management

An admin interface that shows some node statistics and the current open channels with their balances.

screenshot admin channels

Advanced Configuration / Customization

We built this application as a template so you can build your own fancy self-order point of sale screen. You can see a demo video of our version here.

The following chapters will guide you through the steps that are necessary to customize the generic Zeus Server to your needs.

Write your own invoice processor

Invoice processors are invoked after a Lightning Network invoice has been updated. Usually, this means it has been paid/settled. You can write your own invoice processor by implementing ApplicationListener<InvoiceEvent> in your service.

There is an example ch.puzzle.ln.zeus.service.processors.MailSendOrderProcessor service that sends out an e-mail whenever an invoice has been paid:

package ch.puzzle.ln.zeus.service.processors;

import ch.puzzle.ln.zeus.service.InvoiceEvent;
import ch.puzzle.ln.zeus.service.MailService;
import ch.puzzle.ln.zeus.service.dto.InvoiceDTO;
import org.springframework.context.ApplicationListener;
import org.springframework.stereotype.Service;

@Service
public class MailSendOrderProcessor implements ApplicationListener<InvoiceEvent> {

    private final MailService mailService;

    public MailSendOrderProcessor(MailService mailService) {
        this.mailService = mailService;
    }

    @Override
    public void onApplicationEvent(InvoiceEvent event) {
        InvoiceDTO invoice = event.getInvoice();
        
        // Make sure we only send an e-mail if the invoice has been settled
        // for the first time.
        if (invoice.isSettled() && event.isFirstSettleEvent()) {
            mailService.sendOrderConfirmation(invoice);
        }
    }
}

You can customize this however you want.

Build your own web GUI

There is a simple generic example self-order store implemented in the web GUI.

To change the products and their price, make sure to edit the following files:

  • TODO: config file

To change the way the self-order store looks, edit the following files:

  • src/main/webapp/app/shop/self-service.component.html
  • src/main/webapp/app/shop/self-service.component.scss
You can’t perform that action at this time.