Web services and website files for https://lightning.ws
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.



Web services and website files for https://lightning.ws.

lightning.ws hosts paywalled web services / APIs that are payable via the Lightning Network.

It's "eating your own dogfood" for the project ln-paywall. For more information please visit the project's GitHub repository: https://github.com/philippgille/ln-paywall

The Docker image for deploying the web service is on Docker Hub: https://hub.docker.com/r/philippgille/ln-ws-api



  1. Create a data directory on the host: mkdir -p api/data
  2. Copy the tls.cert and invoice.macaroon from your lnd to the api/data directory
  3. Run the web service container with your lnd's address and the Azure translation API key as argument:
    • docker run -d --name ln-ws-api --restart unless-stopped -v $(pwd)/api/data:/root/data philippgille/ln-ws-api -addr "" -translateApiKey "abc123def456" -visionRegion "westus" -visionApiKey "abc123def456"
  4. Run the website and reverse proxy container:
    • docker run -d --name caddy --link ln-ws-api -v $(pwd)/Caddyfile:/etc/Caddyfile -v $HOME/.caddy:/root/.caddy -v $(pwd)/www:/srv/www -p 80:80 -p 443:443 abiosoft/caddy
  5. Either use the interactive client on the website or make the requests programmatically
    • Website: See https://lightning.ws
    • Programmatically:
      1. Send a request to generate an invoice:
        • QR code: curl https://lightning.ws/qr
        • Translation: curl https://lightning.ws/translate
        • OCR (text recognition): curl https://lightning.ws/ocr
      2. Take the invoice from the response body and pay it via the Lightning Network
      3. Send the request again, this time with the preimage as payment proof (hex encoded) and the data as query parameter:
        • QR code: curl -H "x-preimage: 123abc456def" https://lightning.ws/qr?data=testtext
        • Translation: curl -H "x-preimage: 123abc456def" https://lightning.ws/translate?text=Hallo%Welt&to=en
        • OCR: curl -H "x-preimage: 123abc456def" https://lightning.ws/ocr?imageUrl=http%3A%2F%2Fexample%2Ecom%2Fimage%2Epng


The configuration files in this repository only serve for a quick start for testing purposes!

The deployment on https://lightning.ws uses a different, non-public configuration.

In production, you should:

  • Use Redis as storage for ln-paywall to make horizontal scaling of the web service containers possible (you can use the implementation in the storage package of ln-paywall, see here)
    • With persistence for backups and a proper cluster for redundancy
  • Use Docker Swarm or Kubernetes for container orchestration to make it easy to run the containers on a cluster of host machines
    • Set up auto-scaling for the web service containers
  • Add rate limiting and other DoS protection measures
  • Add proper logging (for example using the Elastic Stack, Graylog or a custom combination like Fluent Bit + Elasticsearch + Kibana (see this article))
  • Add proper metric collection (for example with Prometheus + Grafana)
  • Maybe use traefik instead of Caddy as reverse proxy
  • Maybe use nginx for serving the website files
  • ...