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

update

Browse Source
This commit is contained in:
thePR0M3TH3AN
2025-06-21 20:05:12 -04:00
parent 0b03a4945d
commit 01bfb09e09
1 changed files with 41 additions and 126 deletions
Download Patch File Download Diff File Expand all files Collapse all files

167
README.md
View File

@@ -6,178 +6,93 @@ Generate printable flyers with QR codes linking to Tor (.onion) or HTTPS sites,
## 🚀 Key Features ## 🚀 Key Features
// 🔧 merged conflicting changes from codex/populate-gui-text-fields-for-editing vs main * **Interactive setup**: `voxvera init` prompts for metadata or extracts from a PDF form. When editing body text, a small Tkinter GUI window opens with existing content pre‑filled, falling back to the user's `$EDITOR` if the GUI isn't available.
* **Interactive setup**: `voxvera init` prompts for metadata or extracts from a PDF form. When editing body text, a small Tkinter GUI window opens with existing content pre-filled, falling back to the user's `$EDITOR` if the GUI isn't available. * **Template support**: `voxvera init --template <name>` copies built‑in templates (`blank`, `voxvera`).
* **Template support**: `voxvera init --template <name>` copies built-in templates (`blank`, `voxvera`).
* **Build assets**: `voxvera build [--pdf <path>] [--download <file.zip>]` generates HTML, obfuscated JS/CSS, QR codes, and bundles PDFs. * **Build assets**: `voxvera build [--pdf <path>] [--download <file.zip>]` generates HTML, obfuscated JS/CSS, QR codes, and bundles PDFs.
* **Batch import**: `voxvera import` processes all JSON configs in `imports/`. * **Batch import**: `voxvera import` processes all JSON configs in `imports/`.
* **Onion hosting**: `voxvera serve` publishes via Tor/OnionShare and updates flyer links. * **Onion hosting**: `voxvera serve` publishes via Tor/OnionShare and updates flyer links.
* **All-in-one**: `voxvera quickstart` runs init, build, and serve in sequence. * **All‑in‑one**: `voxvera quickstart` runs init, build, and serve in sequence.
* **Dependency check**: `voxvera check` verifies presence of required tools. * **Dependency check**: `voxvera check` verifies presence of required tools.
* **GUI**: Minimal Electron wrapper (`gui/electron`) for non-CLI users. * **GUI**: Minimal Electron wrapper (`gui/electron`) for non‑CLI users.
--- ---
## 📥 Fool-Proof Installation ## 📥 Quick Start (Debian & Ubuntu)
### 1. Prebuilt Binary (Linux) ### 1️⃣ Install VoxVera and all dependencies
```bash ```bash
# Download and install to $HOME/.local/bin # Download the installer
mkdir -p ~/.local/bin \ curl -fsSL https://raw.githubusercontent.com/PR0M3TH3AN/VoxVera/main/voxvera-install.sh -o voxvera-install.sh
&& wget -qO ~/.local/bin/voxvera \ chmod +x voxvera-install.sh
https://github.com/PR0M3TH3AN/VoxVera/releases/latest/download/voxvera \
&& chmod +x ~/.local/bin/voxvera
# Ensure ~/.local/bin is in your PATH # Run the installer (requires sudo for apt packages)
if ! echo "$PATH" | grep -q "$HOME/.local/bin"; then ./voxvera-install.sh
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
echo 'Add ~/.local/bin to your PATH and restart your shell.'
fi
````
### 2. Homebrew (macOS)
```bash
brew tap PR0M3TH3AN/voxvera
brew install voxvera
``` ```
### 3. pipx (cross-platform) The script will:
1. Update **apt** and install Tor, OnionShare, ImageMagick, Poppler, Node.js, and other CLI helpers.
2. Fetch the latest VoxVera release and place it in `~/.local/bin` (creating the directory if needed).
3. Create a minimal per‑user `torrc` under `~/.voxvera/` and (re)start the `tor` service.
After the script finishes, open a new terminal or reload your shell to ensure `~/.local/bin` is on your **PATH**.
### 2️⃣ Run VoxVera (every session)
```bash ```bash
pipx install voxvera # First‑time only: make the wrapper executable
chmod +x voxvera-run.sh
# Start VoxVera
./voxvera-run.sh
``` ```
### 4. From Source `voxvera-run.sh` checks that Tor is healthy, starts it if necessary, and then launches `voxvera quickstart`. Use it every time you work with VoxVera.
```bash
# Download the latest-main branch as a tarball
wget -O VoxVera.tar.gz \
https://github.com/PR0M3TH3AN/VoxVera/archive/refs/heads/main.tar.gz
# Extract it
tar -xzf VoxVera.tar.gz
# Enter the extracted directory (note the “-main” suffix)
cd VoxVera-main
# Create & activate virtualenv
python3 -m venv .venv
source .venv/bin/activate
# Install editable package
pip install --upgrade pip
pip install -e .
```
> After install, verify with `voxvera --help`.
--- ---
## 🛠️ System Dependencies ## 🏗️ Typical Workflow
These tools must be available in your PATH:
```
ton, onionshare-cli, jq, qrencode, convert (ImageMagick), pdftotext,
node, javascript-obfuscator, html-minifier-terser
```
Run `voxvera check` to see missing dependencies.
### Placeholder Tor files
The `voxvera/resources/tor/*` folders only contain small text files named
`placeholder`. VoxVera expects real `tor` and `obfs4proxy` binaries in those
locations when running `voxvera serve` or the Electron GUI.
**Option&nbsp;1: install via your package manager**
```bash
sudo apt update && sudo apt install tor obfs4proxy
# or on macOS
brew install tor obfs4proxy
```
Ensure the Tor daemon is running (`sudo service tor start` on Linux).
**Option&nbsp;2: use the helper script**
```bash
scripts/download_tor.sh
```
The script downloads the official Tor expert bundle for your OS and places the
executables under `voxvera/resources/tor/<platform>`.
After installing either way, set the ports used by Tor:
```bash
export TOR_SOCKS_PORT=9050
export TOR_CONTROL_PORT=9051
```
These variables let OnionShare connect to the already running Tor using its
`--use-running-tor` option. Run `voxvera check` to confirm the binaries are
detected before launching.
---
## 🎮 GUI (Electron)
```bash ```bash
cd gui/electron # 1. Interactive metadata
npm install
voxvera check # verify dependencies before launching
npm start
```
Click **Quickstart** to generate flyers without the terminal. If any tools are
missing or the network fails, see `docs/troubleshooting.md` for fixes.
---
## 🏗️ Basic Usage
```bash
# 1. Interactive setup:
voxvera init voxvera init
# 2. Build flyers: # 2. Build flyers oxvera build --pdf form.pdf --download file.zip # optional flags
voxvera build [--pdf path/to/form.pdf] [--download path/to/file.zip]
# 3. Serve via OnionShare: # 3. Host via Tor
voxvera serve voxvera serve
``` ```
Or run all steps: Or do all three steps in one shot:
```bash ```bash
voxvera quickstart voxvera quickstart
``` ```
### Other Commands Run `voxvera --help` for the full CLI reference.
* `voxvera init --template <name>` — copy a template into `dist/`.
* `voxvera import` — batch-import JSON configs from `imports/`.
* `voxvera check` — dependency health check.
--- ---
## 🐳 Docker (optional) ## 🎮 GUI (optional)
If you prefer a point‑and‑click experience:
```bash ```bash
# Pull and run cd gui/electron
docker pull ghcr.io/PR0M3TH3AN/voxvera:latest npm install
mkdir flyers npm start
docker run --rm -it -v "$(pwd)/flyers:/flyers" ghcr.io/PR0M3TH3AN/voxvera
``` ```
Flyers appear in `./flyers`. The GUI internally calls the same CLI commands, so make sure the installer has run first.
--- ---
## 📄 Documentation ## 📄 Documentation
See the `docs/` folder for detailed guides: See the `docs/` folder for additional guides:
* `docs/usage.md` — CLI workflows * `docs/usage.md` — CLI workflows
* `docs/docker.md` — Docker tips
* `docs/templates.md` — available flyer templates * `docs/templates.md` — available flyer templates
* `docs/troubleshooting.md` — common fixes * `docs/troubleshooting.md` — common fixes
@@ -185,4 +100,4 @@ See the `docs/` folder for detailed guides:
## 📜 License ## 📜 License
MIT © 2025 thePR0M3TH3AN MIT © 2025 thePR0M3TH3AN