0 Fork 0

mirror of https://github.com/PR0M3TH3AN/VoxVera.git synced 2026-10-27 17:50:42 +00:00

Files

T

thePR0M3TH3AN 444a60fb44 Simplify setup: auto Tor config, remove HTTPS hosting, add e2e tests and landing site

- Remove HTTPS hosting option; flyers are served exclusively over Tor
- Auto-detect Tor SOCKS/control ports (no manual env vars needed)
- Auto-set tear-off links to .onion address from serve; keep content
  link user-configurable
- Fix onionshare-cli flags (remove nonexistent --use-running-tor)
- Graceful QR generation when URLs not yet configured
- Add get_tor_ports() with port probing and sensible defaults
- Add e2e test suite including live Tor reachability test
- Add unit tests for port detection, partial URLs, backward compat
- Add site/ directory with VoxVera-generated landing page for voxvera.org
- Rewrite all documentation to reflect simplified workflow
- Add flyer config field reference with char limits and layout diagram

2026-03-13 07:06:35 -04:00

3.8 KiB

Raw Blame History

Detailed Usage

This guide covers common CLI workflows. See docs/docker.md for Docker instructions and docs/templates.md for available flyer templates.

Prerequisites

Install VoxVera with the one-line installer (recommended):

curl -fsSL https://raw.githubusercontent.com/PR0M3TH3AN/VoxVera/main/install.sh | bash

This installs VoxVera, Tor, and OnionShare automatically. If you prefer a manual install:

pipx install 'voxvera@git+https://github.com/PR0M3TH3AN/VoxVera.git@main'
sudo apt install tor onionshare-cli   # Debian/Ubuntu

All build dependencies (QR generation, HTML minification, PDF parsing) are Python packages installed automatically.

Step-by-Step

Run voxvera init and follow the prompts, or use voxvera init --from-pdf path/to/form.pdf to extract fields from a filled PDF form. During init you will configure:
- Flyer metadata (name, title, subtitle, headline)
- Body text (opens in a text editor)
- Content link -- an external URL of your choice (website, download, etc.)
- URL message and binary message
Build the flyer assets. Add an optional zip file with --download:
```
voxvera build --download path/to/file.zip
```
Serve the flyer over Tor:
```
voxvera serve
```
This automatically detects your Tor instance, starts OnionShare, and writes the generated .onion address into the flyer's tear-off links. QR codes are regenerated with the new address.

The generated host/<subdomain> directory contains all flyer files. The index.html file fetches config.json at runtime, so the flyer must be served via a web server (OnionShare handles this). Visitors can use the Download button to retrieve any bundled files.

How URLs Work

Each flyer has two separate URLs:

Tear-off link (auto-generated): The .onion address where the flyer is hosted. Written into every tear-off tab with a QR code. People who tear off a tab can visit the site to view/reprint the flyer.
Content link (user-configured): Any external URL you choose during voxvera init. Displayed in the main body of the flyer with its own QR code. Can point to a website, video, download, or anything else.

You do not need to manually enter the .onion address -- voxvera serve handles this automatically.

Batch Import

Place configuration files in an imports/ directory at the project root and run:

voxvera import

Each JSON file is copied to src/config.json and processed with voxvera build. Existing folders under host/ with the same subdomain are cleaned before new files are written. OnionShare session keys (.onionshare-session) are preserved so the onion URL stays the same across re-imports.

Hosting with OnionShare

Use the CLI to publish the flyer over Tor:

voxvera serve

Tor ports are auto-detected from your running Tor instance (defaults: SOCKS 9050, control 9051). You can override detection with environment variables if needed:

TOR_SOCKS_PORT=9150 TOR_CONTROL_PORT=9151 voxvera serve

The command launches onionshare-cli in persistent website mode, waits for the generated onion URL, writes it into config.json as the tear-off link, regenerates QR codes, and copies updated files into the host directory.

The onion URL is derived from an Ed25519 keypair stored in host/<subdomain>/.onionshare-session. As long as this file exists, the URL stays the same even if you rebuild with new content. Keep OnionShare running to continue hosting.

All-in-One

voxvera quickstart                # interactive
voxvera quickstart --non-interactive  # use existing config.json

Or use the helper script which ensures Tor is running first:

./voxvera-run.sh

Checking Dependencies

voxvera check

This verifies that required Python packages and external tools (onionshare-cli) are available and prints a summary.

3.8 KiB Raw Blame History