mirror of
https://github.com/PR0M3TH3AN/VoxVera.git
synced 2025-09-08 06:58:42 +00:00
150 lines
4.7 KiB
Markdown
150 lines
4.7 KiB
Markdown
# VoxVera Flyers
|
||
|
||
VoxVera provides scripts and templates for producing printable flyers with QR codes. These flyers link to content hosted through Tor and can also include a Nostr page. The project automates building the HTML, generating the QR codes, and copying all assets into a directory under `host/` so they can be served statically.
|
||
|
||
## TL;DR
|
||
|
||
```bash
|
||
git clone https://github.com/PR0M3TH3AN/VoxVera.git
|
||
cd VoxVera
|
||
./install.sh # use install.ps1 on Windows
|
||
voxvera quickstart
|
||
```
|
||
|
||
See [docs/usage.md](docs/usage.md) for detailed usage instructions.
|
||
|
||
## Quick Install
|
||
|
||
Run the installer to set up all dependencies and the `voxvera` CLI in one step.
|
||
|
||
If you already have the prerequisites you can install the package directly from
|
||
PyPI:
|
||
|
||
```bash
|
||
pipx install voxvera # recommended
|
||
# or
|
||
pip install --user voxvera
|
||
```
|
||
|
||
The legacy `src/create_flyer.sh` script remains for backward compatibility. It
|
||
simply forwards its arguments to the Python CLI so existing workflows continue
|
||
to work.
|
||
|
||
### GUI
|
||
An Electron wrapper is provided under `gui/electron` for users that prefer a graphical interface.
|
||
Run it with:
|
||
|
||
```bash
|
||
cd gui/electron
|
||
npm install
|
||
npm start
|
||
```
|
||
|
||
### Linux/macOS
|
||
|
||
```bash
|
||
curl -fsSL https://raw.githubusercontent.com/PR0M3TH3AN/VoxVera/main/install.sh | bash
|
||
```
|
||
|
||
### Windows PowerShell
|
||
|
||
```powershell
|
||
irm https://raw.githubusercontent.com/PR0M3TH3AN/VoxVera/main/install.ps1 | iex
|
||
```
|
||
|
||
## Prerequisites
|
||
- **Node.js** and **npm**
|
||
- **jq**
|
||
- **qrencode**
|
||
- **ImageMagick** (`convert`)
|
||
- **javascript-obfuscator** and **html-minifier-terser** (installed via npm)
|
||
- **pdftotext** (optional, used when extracting fields from a PDF form)
|
||
- **Python packages** [`InquirerPy`](https://github.com/kazhala/InquirerPy) and [`rich`](https://github.com/Textualize/rich)
|
||
|
||
## Installing Dependencies
|
||
|
||
On Debian or Ubuntu systems you can install the required packages with:
|
||
|
||
```bash
|
||
sudo apt update
|
||
sudo apt install -y jq qrencode imagemagick poppler-utils nodejs npm
|
||
```
|
||
|
||
### macOS
|
||
|
||
With [Homebrew](https://brew.sh) you can install the same dependencies:
|
||
|
||
```bash
|
||
brew install jq qrencode imagemagick poppler node coreutils
|
||
```
|
||
|
||
The obfuscation scripts attempt to use `mktemp --suffix` when creating
|
||
temporary files. If that option is unavailable – for example on macOS without
|
||
GNU `coreutils` – the scripts automatically fall back to a portable `mktemp`
|
||
command that yields the same result.
|
||
|
||
The obfuscation scripts also rely on a pair of Node modules. Install them
|
||
globally:
|
||
|
||
```bash
|
||
npm install -g javascript-obfuscator html-minifier-terser
|
||
```
|
||
|
||
Install the Python dependencies:
|
||
|
||
```bash
|
||
pip install --user InquirerPy rich
|
||
```
|
||
|
||
A helper script `setup.sh` is provided to check for these dependencies and
|
||
install anything that is missing.
|
||
|
||
### Windows
|
||
|
||
These scripts rely on a Unix-like environment. The recommended approach on
|
||
Windows is to use **WSL2** with a Debian distribution. Install WSL and Debian
|
||
with:
|
||
|
||
```powershell
|
||
wsl --install
|
||
```
|
||
|
||
Launch the Debian terminal and run `setup.sh` from this repository or the
|
||
`apt` commands shown above to install all prerequisites. Alternative
|
||
environments such as **MSYS2** or **Git Bash** can also be used, but they must
|
||
provide the same command-line utilities.
|
||
|
||
## Generating a Flyer
|
||
Run the CLI from the repository root:
|
||
|
||
```bash
|
||
# interactive prompts
|
||
voxvera init
|
||
|
||
# use an alternate config file
|
||
voxvera init --config path/to/custom.json
|
||
|
||
# use answers from an existing PDF form
|
||
voxvera init --from-pdf path/to/form.pdf
|
||
```
|
||
|
||
When run interactively you'll be prompted for details such as the flyer title
|
||
and headline. The script now also asks for a **URL** and a **Tear-off link**.
|
||
These values are written into the configuration file (`src/config.json` by
|
||
default) and determine the QR code targets.
|
||
|
||
The script updates the chosen config file, regenerates QR codes, obfuscates `index-master.html` and `nostr-master.html`, and copies the resulting files plus PDFs and QR images into `host/<subdomain>`. The resulting `src/index.html` and `src/nostr.html` files are generated automatically and excluded from version control via `.gitignore`. The contents in that directory can then be hosted.
|
||
|
||
Additional documentation is available in the `src/` directory; see [src/README.md](src/README.md) for more details on the obfuscation scripts and additional usage notes.
|
||
|
||
Additional documentation, including step-by-step instructions and hosting guides, lives under the [docs](docs/) directory.
|
||
|
||
## Packages
|
||
Prebuilt binaries are published on the releases page. Linux users can run the
|
||
`packaging/build_appimage.sh` script after a PyInstaller build to create a
|
||
portable AppImage. Homebrew and Chocolatey formulas are provided under
|
||
`packaging/` for easy upgrades on macOS and Windows.
|
||
|
||
|
||
This project is licensed under the [MIT License](./LICENSE).
|