error-try-again / QRGen

Full-Stack QR Code generation service for self-hosting

QRGen - A self-hostable Fullstack QR code generation service

TS (Express/Backend), TSX (Vite/React/Frontend), Bash/Shell (Automation)

Overview

This project aims to automate the setup of a scalable, self-hostable, full-stack QR code generation service within a rootless Docker environment, with a focus on security & ease of use. The project has been written in TS (Express), TSX (Vite/React), Bash/Shell (Automation) and has several key layers. Each of which deserve their own companion documentation. To address the challenge of supporting multiple stack configurations, the project has gone through several iterations since its inception. Currently, it is comprised of two separate git submodules that are initialized within the containers themselves at build time.

Note: If you're looking for a version of this project that does not use submodules and instead copies sources from the host/docker-primary user, see the legacy branch.

The first submodule is an optional backend (Express) which provides an operational mode where QR codes are generated on the server. This is a complex design decision and is in preparation for a full-release version of the application, which will support several additional features such as link shortening/dynamic linking, QR code generation history, administrative configuration, user accounts/auth. This decision aims to provide an additional layer of security to the generation process, preventing certain types of speculative malicious QR injection & redirection attacks. To read more about planned features, skip to the Roadmap section.

The second submodule is a requisite frontend (Vite/React) that provides a simple, responsive, and mobile-friendly UI for generating QR codes. The module can be run in isolation or in conjunction with the backend submodule depending on your use case.

The idea was initially conceived when I found myself needing to generate a large number of QR codes for a project, and I was unable to find a suitable self-hostable solution, so I decided to build my own. I hope that others find it useful too.

Continuous improvements and bug fixes are expected. Contributions, issues & pull requests welcome. If you have a specific fix for the frontend or backend environments, please submit your pull request to the respective submodule/repo.

A full write up and comprehensive documentation is underway here, but for now, here's a quick overview of the project.

Live Demo

Link to Live Demo - Sydney, Australia

If the demo server is is down for maintenance, it's probably worth checking back in a couple hours

Desktop Examples

Firefox Dark

Firefox Light

Features

QRGen supports the the QR Code generation in the following formats for both bulk and regular code generation

• Text
• URLs & links
• SMS
• Email
• Events
• Phone
• Geolocation
• Wifi
• Zoom
• Digital Contact Cards
• Crypto Currencies
• Google Reviews (user provided API key)

UI

• Dark mode, responsive, and mobile/tablet friendly design with a focus on accessibility and usability.

Tech

• Self-hostable QR code generation
• Supports custom domains and subdomains, custom ports, etc.
• Various formats and sizes, with multiple error correction levels.
• Highly automated & scalable.
• Self-signed SSL certificate generation.
• LetsEncrypt certificate automation for staging & production environments.
• Automated SSL certificate renewal via cron.
• Rootless & Dockerized.
• Security features such as CORS, rate limiting, OCSP stapling, HSTS, and more.
• NGINX proxy provides multi-service integrations.
• Provides QR Generation web APIs (POST /qr/generate) or (POST /qr/batch)
• Installer script for easy setup and configuration with automatic and custom configuration options.

Performance

Page Insights Scores

Lighthouse Scores

SSL Labs scores

High level project overview

Bash:
    depends.sh:
    - A minimal dependency installer/uninstaller for apt packages, user setup, NVM setup (root)
    
    install.sh:
    - A rootless installer for docker, environment configurations, and user prompts. 
    - Automated deployment and generation of Compose config files, Dockerfiles, and dependencies.
    - Certbot command generation and more.

Python:
    - Modified Certbot fork in a Docker container for automatic certificate mergers between self-signed and Let's Encrypt certificates.

NGINX:
    - Proxies queries between frontend/backend services.
    - Adds security headers and handles TLS with strong cipher suites.
    - Manages ACME challenge for Certbot.

Compose:
    - Simplifies container and volume management.
    - Manages virtual network configuration and associated port assignments.

Express Backend (TypeScript):
    - Manages query validation mappings and security features (Helmet, CORS, rate limiting.)
    - API for generating and batching QR data.

React Frontend (TSX/Vite):
    - Utilizes React for its efficient state management and context API.
    - Vite for bundling and testing integrations.

Tested on:

• on Ubuntu 22.04.3 LTS, jammy, 5.15.0-87-generic SMP x86_64 GNU/Linux
• on Pop!_OS 22.04 LTS, jammy, 6.5.6-76060506-generic SMP x86_64 GNU/Linux

Local Setup:

Run the dependency installation script

cd ~ && git clone https://github.com/error-try-again/QRGen.git && cd QRGen && chmod +x depends.sh && sudo ./depends.sh
# Select 1) Full Installation (All)

Enter into a new shell with the newly created user, run project installation script.

cd ~ && cd QRGen && machinectl shell docker-primary@ $HOME/QRGen/install.sh

Welcome to the QRGen setup script!
1) Run Setup				6) Update Project
2) Run Mock Configuration		7) Stop Project Docker Containers
3) Uninstall				8) Purge Current Builds - Dangerous
4) Reload/Refresh			9) Quit
5) Dump logs
# Select 1)

Remote Setup:

Step 1

With keys, without ssh root-login, run the dependency installation script

# Connect to your remote host
ssh -i .ssh/<yourkey> <generic-user>@<hostip>

# Download dependency installer
wget https://raw.githubusercontent.com/error-try-again/QRGen/main/depends.sh && chmod +x depends.sh

# Elevate user
sudo su

# Run dependency installer 
sudo ./depends.sh
# Select 1) Full Installation (All)

# Exit root user, exit ssh session
exit && exit

Step 2

Create fresh user ssh key, run the project installation script

# Setup fresh user key locally
ssh-keygen
ssh-copy-id -i ~/.ssh/<a-fresh-public-key> docker-primary@<hostip>

# Use your fresh key to remote in & modify the main_install_profiles.json file to your liking (for auto-setup)
# Or, run the installer manually and select your desired options through custom prompts
ssh -t -i .ssh/<a-fresh-public-key> docker-primary@<hostip> 
cd ~ && git clone https://github.com/error-try-again/QRGen.git && cd QRGen && nano main_install_profiles.json && ~/QRGen/install.sh

# Select 1)

Usage

For a more detailed usage guide, head over to the project documentation.

Healthcheck Setup (Optional)

Guide to Installing Upptime on a Self-Hosted Runner

Roadmap

• Add import mechanism for QR code generation (CSV, JSON, Excel, etc.)
• API Documentation
• Improved CI/CD pipeline
• Improved test coverage
• Additional deployment options (E.g. Kubernetes, etc.)
• Admin panel for tunable settings (E.g. SSL configuration, rate limiting, content persistence, content expiry, etc.)
• Database support (E.g. MongoDB, etc.) for hosted content persistence (E.g. QR code generation history, dynamic QR code generation & linking, etc.)
• Rewrite the installer in Python
• Logo options & other customizations

Setup Screenshots

Local Install

HTTP only

Staging environment

Production environment

!

Self-signed SSL certificate

Pruning containers

Updating

Stopping containers