386 lines
15 KiB
Markdown
386 lines
15 KiB
Markdown
# Cipher · Barcode Studio
|
||
|
||
A self-contained, browser-based barcode generator that converts text or numeric sequences into 22 different barcode symbologies and exports them as downloadable JPG (or PNG) images. Designed to run as a single hardened Docker container with no backend, no database, and no telemetry — everything happens in the user's browser.
|
||
|
||
  
|
||
|
||
---
|
||
|
||
## Table of Contents
|
||
|
||
1. [Features](#features)
|
||
2. [Supported Barcode Formats](#supported-barcode-formats)
|
||
3. [Architecture](#architecture)
|
||
4. [Requirements](#requirements)
|
||
5. [Quick Start](#quick-start)
|
||
6. [Configuration](#configuration)
|
||
7. [Project Structure](#project-structure)
|
||
8. [Security](#security)
|
||
9. [Dependency Versions & Vulnerability Status](#dependency-versions--vulnerability-status)
|
||
10. [Operations](#operations)
|
||
11. [Updating & Maintenance](#updating--maintenance)
|
||
12. [Troubleshooting](#troubleshooting)
|
||
13. [Development](#development)
|
||
14. [License](#license)
|
||
|
||
---
|
||
|
||
## Features
|
||
|
||
* **22 barcode symbologies** spanning retail/GS1, linear/industrial, pharma, postal and 2D matrix codes.
|
||
* **Live example preview** — every symbology shows a sample render the moment it's selected.
|
||
* **Batch generation** — paste lines into the input area and each line becomes its own barcode card.
|
||
* **Per-card text toggle** — show or hide the human-readable caption beneath each barcode, then download it in that state.
|
||
* **JPG and PNG export** — individual downloads per barcode plus a one-click "Download All as JPG" for the whole batch.
|
||
* **Adjustable scale and JPG quality** for print-ready output.
|
||
* **Fully offline-capable** once loaded — every library is vendored locally, no third-party CDN at runtime (web fonts are the only external request and are optional).
|
||
* **No backend** — runs entirely as static assets served by nginx. No database, no API, no user data leaves the browser.
|
||
|
||
---
|
||
|
||
## Supported Barcode Formats
|
||
|
||
| Group | Symbology | Notes |
|
||
|---|---|---|
|
||
| Retail · GS1 | EAN-13, EAN-8, UPC-A, UPC-E, ISBN-13, GS1 DataBar, GS1-128 | ISBN-10 auto-converts to ISBN-13 |
|
||
| Linear · Industrial | Code-128, Code-39, Code-39 Full ASCII, Code-93, Code-11, Code 2of5 Interleaved, MSI Plessey, Flattermarken, Telepen Alpha | |
|
||
| Pharma · Specialty | Pharmacode One-Track, Pharmacode Two-Track | Laetus binary codes |
|
||
| Postal | KIX | Dutch PostNL routing |
|
||
| 2D · Matrix | QR Code, Data Matrix, PDF417 | |
|
||
|
||
---
|
||
|
||
## Architecture
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ Browser │
|
||
│ ┌───────────────────────────────────────────────────┐ │
|
||
│ │ index.html (UI + state) │ │
|
||
│ │ ├── JsBarcode (linear codes) │ │
|
||
│ │ └── bwip-js (specialty + 2D codes) │ │
|
||
│ │ ─→ HTMLCanvasElement → JPG / PNG Blob │ │
|
||
│ └───────────────────────────────────────────────────┘ │
|
||
└──────────────────────────────┬──────────────────────────────┘
|
||
│ HTTP (static assets only)
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ Docker container · nginx 1.30.1 · alpine 3.23 │
|
||
│ • runs as non-root (UID 101) │
|
||
│ • read-only root filesystem │
|
||
│ • all caps dropped, no-new-privileges │
|
||
│ • CSP / HSTS / nosniff / X-Frame-Options / COOP / CORP │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
Encoding happens **entirely in the browser** — the container only ships static HTML/JS. The image cannot leak data because there is no application server to leak through.
|
||
|
||
---
|
||
|
||
## Requirements
|
||
|
||
| Component | Minimum version | Why |
|
||
|---|---|---|
|
||
| Docker Engine | **24.0+** | Buildkit, compose-v2 features |
|
||
| Docker Compose | **v2.20+** | Modern compose schema (`deploy.resources`, `tmpfs` options) |
|
||
| Host OS | Linux / macOS / Windows (WSL2) | Anything Docker supports |
|
||
| RAM | 64 MB free | Container reserves 32 MB, caps at 128 MB |
|
||
| Disk | ~50 MB | Image is ~40 MB |
|
||
| Open port | one host port (default 8080) | Reconfigurable via `.env` |
|
||
|
||
Verify your toolchain:
|
||
|
||
```bash
|
||
docker --version # → Docker version 24.x.x or newer
|
||
docker compose version # → Docker Compose version v2.20+ or newer
|
||
```
|
||
|
||
If you're on an older Docker that only has the standalone `docker-compose` binary, the file still works — just replace `docker compose` with `docker-compose` in the commands below.
|
||
|
||
---
|
||
|
||
## Quick Start
|
||
|
||
```bash
|
||
# 1. Unzip and enter the project
|
||
unzip cipher-barcode-studio.zip
|
||
cd cipher-barcode-studio
|
||
|
||
# 2. (Optional) override the host port
|
||
cp .env.example .env # then edit HOST_PORT if needed
|
||
|
||
# 3. Build and start
|
||
docker compose up -d --build
|
||
|
||
# 4. Open in browser
|
||
# http://localhost:8080
|
||
```
|
||
|
||
That's it. To stop:
|
||
|
||
```bash
|
||
docker compose down
|
||
```
|
||
|
||
To stop and remove the built image as well:
|
||
|
||
```bash
|
||
docker compose down --rmi local
|
||
```
|
||
|
||
---
|
||
|
||
## Configuration
|
||
|
||
All runtime configuration lives in `.env` (copied from `.env.example`):
|
||
|
||
| Variable | Default | Description |
|
||
|---|---|---|
|
||
| `HOST_PORT` | `8080` | Port published on the host machine |
|
||
|
||
The container itself always listens on `8080` internally — only the host-side port is configurable.
|
||
|
||
### Putting it behind a reverse proxy
|
||
|
||
If you're running this behind Traefik, Caddy, nginx, or similar:
|
||
|
||
```yaml
|
||
# example with Traefik labels
|
||
services:
|
||
cipher:
|
||
# ...existing config...
|
||
labels:
|
||
- "traefik.enable=true"
|
||
- "traefik.http.routers.cipher.rule=Host(`barcode.example.com`)"
|
||
- "traefik.http.routers.cipher.tls=true"
|
||
- "traefik.http.routers.cipher.tls.certresolver=letsencrypt"
|
||
- "traefik.http.services.cipher.loadbalancer.server.port=8080"
|
||
```
|
||
|
||
When fronted by HTTPS, the `Strict-Transport-Security` header in `nginx.conf` will kick in automatically.
|
||
|
||
---
|
||
|
||
## Project Structure
|
||
|
||
```
|
||
cipher-barcode-studio/
|
||
├── docker-compose.yml # Orchestration + runtime hardening
|
||
├── Dockerfile # Image build steps
|
||
├── .dockerignore # Keep the build context lean
|
||
├── .env.example # Template for runtime config
|
||
├── LICENSE # MIT + third-party attributions
|
||
├── README.md # You are here
|
||
├── nginx/
|
||
│ └── nginx.conf # Hardened nginx config w/ CSP & security headers
|
||
└── web/
|
||
├── index.html # The full application (single HTML file)
|
||
└── vendor/
|
||
├── JsBarcode.all.min.js
|
||
└── bwip-js-min.js
|
||
```
|
||
|
||
---
|
||
|
||
## Security
|
||
|
||
This image is built with a defense-in-depth posture even though it serves static content with no user data:
|
||
|
||
### Container hardening
|
||
|
||
| Control | Mechanism |
|
||
|---|---|
|
||
| Non-root execution | Image's `USER` is `nginx` (UID 101). Compose pins `user: "101:101"`. |
|
||
| Read-only rootfs | `read_only: true` in compose; writable paths exposed via `tmpfs`. |
|
||
| Capability drop | `cap_drop: [ALL]` — no Linux capabilities granted. |
|
||
| No privilege escalation | `security_opt: no-new-privileges:true`. |
|
||
| Resource limits | CPU capped at 0.5 cores, memory at 128 MB. |
|
||
| Minimal base | `nginxinc/nginx-unprivileged:alpine3.23-slim` — Alpine, no extra packages, security upgrades applied at build. |
|
||
| Restricted log size | json-file driver capped at 5 MB × 3 rotations. |
|
||
|
||
### HTTP hardening (in `nginx/nginx.conf`)
|
||
|
||
| Header | Purpose |
|
||
|---|---|
|
||
| `Content-Security-Policy` | Restricts scripts/styles/fonts/images to `self` + Google Fonts only |
|
||
| `Strict-Transport-Security` | One-year HSTS with subdomain coverage (effective behind TLS) |
|
||
| `X-Frame-Options: DENY` + CSP `frame-ancestors 'none'` | Clickjacking protection |
|
||
| `X-Content-Type-Options: nosniff` | Disables MIME sniffing |
|
||
| `Referrer-Policy: strict-origin-when-cross-origin` | Limits referrer leakage |
|
||
| `Permissions-Policy` | Disables camera, mic, geolocation, USB, payment APIs |
|
||
| `Cross-Origin-Opener-Policy: same-origin` | Window isolation |
|
||
| `Cross-Origin-Resource-Policy: same-origin` | Resource isolation |
|
||
| `server_tokens off` | Hides nginx version |
|
||
|
||
Also: request size capped at 1 KB (this is a static GET-only service), hidden files (`/\.`) blocked, `/healthz` lightweight endpoint for orchestrators.
|
||
|
||
### Supply chain
|
||
|
||
* JavaScript libraries are **vendored** under `web/vendor/`, not loaded from CDN at runtime.
|
||
* Each `<script>` tag in `index.html` carries a **Subresource Integrity (SRI)** hash (`sha384`), so any tampering with the vendor files will cause the browser to refuse execution.
|
||
* The only runtime third-party connection is to Google Fonts for typography. If you need full air-gap operation, see [Removing Google Fonts](#removing-google-fonts).
|
||
|
||
### Scanning the image yourself
|
||
|
||
```bash
|
||
docker compose build
|
||
docker scout cves cipher-barcode-studio:1.0.0 # native Docker scanner
|
||
# or
|
||
trivy image cipher-barcode-studio:1.0.0 # Trivy
|
||
# or
|
||
grype cipher-barcode-studio:1.0.0 # Grype
|
||
```
|
||
|
||
Expect findings to be limited to base-image OS packages; the application itself has no Node.js, npm, or other runtime dependencies to scan.
|
||
|
||
---
|
||
|
||
## Dependency Versions & Vulnerability Status
|
||
|
||
All versions verified against published CVE feeds at build time.
|
||
|
||
| Component | Pinned version | Latest as of build | Known CVEs | Source of truth |
|
||
|---|---|---|---|---|
|
||
| nginx | `1.30.1` | 1.30.1 (stable) | none active | [nginx security advisories](https://nginx.org/en/security_advisories.html) |
|
||
| Alpine Linux | `3.23` | 3.23 | base image kept patched via `apk upgrade` in Dockerfile | [Alpine secdb](https://secdb.alpinelinux.org/) |
|
||
| JsBarcode | `3.12.3` | 3.12.3 | 0 | [Snyk advisor](https://snyk.io/advisor/npm-package/jsbarcode), [Socket](https://socket.dev/npm/package/jsbarcode) |
|
||
| bwip-js | `4.10.1` | 4.10.1 | 0 | [Snyk advisor](https://security.snyk.io/package/npm/bwip-js) |
|
||
|
||
The build pulls `nginxinc/nginx-unprivileged:1.30.1-alpine3.23-slim` and then runs `apk upgrade --no-cache` so any Alpine package CVEs disclosed after the image was published are still patched.
|
||
|
||
If you fork this repo, re-run the vulnerability check periodically:
|
||
|
||
```bash
|
||
docker compose build --no-cache
|
||
trivy image --severity HIGH,CRITICAL cipher-barcode-studio:1.0.0
|
||
```
|
||
|
||
---
|
||
|
||
## Operations
|
||
|
||
### View logs
|
||
|
||
```bash
|
||
docker compose logs -f cipher
|
||
```
|
||
|
||
### Healthcheck
|
||
|
||
```bash
|
||
docker inspect --format='{{json .State.Health}}' cipher-barcode-studio | jq
|
||
# or hit it directly:
|
||
curl -i http://localhost:8080/healthz
|
||
```
|
||
|
||
### Restart
|
||
|
||
```bash
|
||
docker compose restart cipher
|
||
```
|
||
|
||
### Inspect security posture of the running container
|
||
|
||
```bash
|
||
docker inspect cipher-barcode-studio | jq '.[0].HostConfig | {ReadonlyRootfs, CapDrop, SecurityOpt, Memory, NanoCpus}'
|
||
```
|
||
|
||
Expected output should include `"ReadonlyRootfs": true`, `"CapDrop": ["ALL"]`, and `"no-new-privileges:true"`.
|
||
|
||
---
|
||
|
||
## Updating & Maintenance
|
||
|
||
### Rebuild with the latest patches
|
||
|
||
```bash
|
||
docker compose build --no-cache --pull
|
||
docker compose up -d
|
||
```
|
||
|
||
`--pull` forces Docker to refetch the base image, ensuring you pick up new Alpine and nginx releases.
|
||
|
||
### Update a vendored JS library
|
||
|
||
```bash
|
||
cd web/vendor
|
||
|
||
# Example: bump bwip-js
|
||
curl -sSL -o bwip-js-min.js "https://cdn.jsdelivr.net/npm/bwip-js@<new-version>/dist/bwip-js-min.js"
|
||
|
||
# Recompute the SRI hash
|
||
openssl dgst -sha384 -binary bwip-js-min.js | openssl base64 -A | xargs -I{} echo "sha384-{}"
|
||
|
||
# Paste the new hash into the integrity="" attribute in web/index.html
|
||
# Rebuild
|
||
docker compose up -d --build
|
||
```
|
||
|
||
### Removing Google Fonts
|
||
|
||
If you need a fully air-gapped install, edit `web/index.html`:
|
||
|
||
1. Delete the three `<link rel="preconnect">` and `<link rel="stylesheet">` tags pointing at `fonts.googleapis.com` / `fonts.gstatic.com`.
|
||
2. The page still works — it just falls back to the next font in each `font-family` stack (`serif` / `monospace`).
|
||
3. Tighten `nginx/nginx.conf` by removing the `https://fonts.googleapis.com` and `https://fonts.gstatic.com` entries from the CSP.
|
||
|
||
---
|
||
|
||
## Troubleshooting
|
||
|
||
| Symptom | Cause | Fix |
|
||
|---|---|---|
|
||
| `bind: address already in use` | Port 8080 is taken | Set `HOST_PORT=8081` (or any free port) in `.env` and `docker compose up -d` |
|
||
| Container restart-loops with "Permission denied" on `/var/cache/nginx` | Older Docker without tmpfs option support | Upgrade Docker Engine to 24+ |
|
||
| Browser shows blank page, console says "Refused to execute script ... integrity" | Vendor file modified locally without updating SRI | Recompute SRI hash (see [Updating](#update-a-vendored-js-library)) |
|
||
| Fonts look generic | Network blocks Google Fonts | Either allow `fonts.googleapis.com` / `fonts.gstatic.com` or follow [Removing Google Fonts](#removing-google-fonts) |
|
||
| QR / Data Matrix barcode renders but caption is cut off | Output is a 2D code with long text | Hide the text via the per-card "Hide text" button, or shorten the input |
|
||
| `docker compose` not found | Only the legacy standalone `docker-compose` is installed | Use `docker-compose up -d --build` instead; or install the v2 plugin |
|
||
|
||
### Resetting from scratch
|
||
|
||
```bash
|
||
docker compose down --rmi local --volumes
|
||
docker compose up -d --build --force-recreate
|
||
```
|
||
|
||
---
|
||
|
||
## Development
|
||
|
||
To iterate on the UI without rebuilding the image every time, mount `web/` over the container's webroot:
|
||
|
||
```yaml
|
||
# docker-compose.override.yml (gitignored convention)
|
||
services:
|
||
cipher:
|
||
volumes:
|
||
- ./web:/usr/share/nginx/html:ro
|
||
```
|
||
|
||
Then:
|
||
|
||
```bash
|
||
docker compose up -d
|
||
# edit web/index.html, refresh the browser — no rebuild needed
|
||
```
|
||
|
||
When you're done, delete the override file and rebuild for production.
|
||
|
||
---
|
||
|
||
## License
|
||
|
||
This project is released under the **MIT License** — see [LICENSE](./LICENSE).
|
||
|
||
Third-party libraries retain their own licenses:
|
||
|
||
* **JsBarcode** — MIT — https://github.com/lindell/JsBarcode
|
||
* **bwip-js** — MIT — https://github.com/metafloor/bwip-js
|
||
* **nginx** — BSD-2-Clause — https://nginx.org/LICENSE
|
||
* **Alpine Linux** — MIT-equivalent — https://alpinelinux.org/
|
||
|
||
---
|
||
|
||
*Built with care. Encode anything. Print everything.*
|