diff --git a/.gitignore b/.gitignore index 3108e3f..8cbd517 100644 --- a/.gitignore +++ b/.gitignore @@ -1,7 +1,8 @@ # Temporary files *.tmp tmp*/ - +venv/ +.venv # OS and editor files .DS_Store Thumbs.db diff --git a/README.md b/README.md index e371203..b1d0754 100644 --- a/README.md +++ b/README.md @@ -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/`. 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 \ No newline at end of file