thePR0M3TH3AN/VoxVera
1
0
Fork 0
mirror of https://github.com/PR0M3TH3AN/VoxVera.git synced 2025-09-07 14:38:42 +00:00
Code Issues Packages Projects Releases Wiki Activity

update

Browse Source
This commit is contained in:
thePR0M3TH3AN
2025-06-21 13:54:40 -04:00
parent c7fa0dc1e4
commit 67a77df6e4
2 changed files with 69 additions and 155 deletions
Download Patch File Download Diff File Expand all files Collapse all files

221
README.md
View File

@@ -1,184 +1,97 @@
# 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.
Generate printable flyers with QR codes that link to Tor (.onion) or HTTPS sites, plus an optional Nostr address.
## TL;DR
---
## 🎉 Quick Install (no Git, no pip hassles)
1. **Download the prebuilt Linux binary**
```bash
mkdir -p ~/.local/bin
wget -qO ~/.local/bin/voxvera \
https://github.com/PR0M3TH3AN/VoxVera/releases/latest/download/voxvera
chmod +x ~/.local/bin/voxvera
```
2. **Ensure `$HOME/.local/bin` is in your `PATH`**
Add this to your `~/.bashrc` or `~/.zshrc` if needed:
```bash
export PATH="$HOME/.local/bin:$PATH"
```
3. **Run the CLI**
```bash
voxvera quickstart
```
---
## 🛠️ From Source (for contributors)
If you want to hack on VoxVera, clone the repo and use a virtual env:
```bash
# 1. Clone the repo
git clone https://github.com/PR0M3TH3AN/VoxVera.git
cd VoxVera
./install.sh # use install.ps1 on Windows
# 2. Create & activate a Python venv
python3 -m venv .venv
source .venv/bin/activate
# 3. Install the package
pip install --upgrade pip
pip install .
# 4. Run
voxvera quickstart
```
See [docs/usage.md](docs/usage.md) for detailed usage instructions.
---
## Quick Install
## 📦 Docker (optional)
Run the installer to set up the core dependencies and install the `voxvera` CLI.
The script installs Tor, OnionShare, `jq`, `qrencode`, and ImageMagick before
fetching the latest release of the CLI. Run `setup.sh` to install additional
dependencies such as Node.js, `javascript-obfuscator`, `html-minifier-terser`,
and the Python packages `InquirerPy` and `rich` if they are not already
available.
If you already have the prerequisites you can install the package directly. The
project is not currently published on PyPI, so install it from the repository:
VoxVera is also on GitHub Container Registry:
```bash
pipx install git+https://github.com/PR0M3TH3AN/VoxVera.git # recommended
# or from the current directory
pip install .
docker pull ghcr.io/PR0M3TH3AN/voxvera:latest
mkdir flyers
docker run --rm -it -v "$(pwd)/flyers:/flyers" ghcr.io/PR0M3TH3AN/voxvera
```
If your system reports an "externally-managed" Python environment and blocks
installation, create a virtual environment first:
Generated flyers land in `./flyers`.
---
## 🚀 Usage
```bash
python3 -m venv voxvera-venv
source voxvera-venv/bin/activate
pip install git+https://github.com/PR0M3TH3AN/VoxVera.git
```
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
```
`setup.sh` also installs the required Python packages automatically. If you
prefer to install them manually, run:
```bash
pip install --user InquirerPy rich
```
The script checks for these dependencies and installs 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 any directory:
```bash
# interactive prompts
# Initialize a new flyer (interactive prompts)
voxvera init
# use an alternate config file
voxvera init --config path/to/custom.json
# Build the HTML, QR codes & static files
voxvera build
# use answers from an existing PDF form
voxvera init --from-pdf path/to/form.pdf
# Host via OnionShare on Tor
voxvera serve
```
After updating the configuration run the build step. You can optionally
include a zip file that visitors can download:
See `voxvera check` to verify you have `tor`, `onionshare-cli`, `jq`, `qrencode`, `imagemagick`, `node`, `javascript-obfuscator`, and `html-minifier-terser`.
```bash
voxvera build --download path/to/file.zip
```
---
If `--download` is omitted the CLI looks for `src/download/download.zip` and
copies it into the output directory.
## 📄 Docs
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.
Full docs in the `docs/` folder:
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.
* `docs/usage.md` — detailed CLI guide
* `docs/docker.md` — Docker tips
* `docs/troubleshooting.md` — common fixes
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.
## 📜 License
## 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.
## Running Tests
The test suite relies on the Python packages
[InquirerPy](https://github.com/kazhala/InquirerPy) and
[rich](https://github.com/Textualize/rich). Install them with:
```bash
pip install -r requirements.txt
```
Then execute the tests using `pytest`.
This project is licensed under the [MIT License](./LICENSE).
MIT © 2025 thePR0M3TH3AN