mirror of
https://github.com/PR0M3TH3AN/VoxVera.git
synced 2026-11-07 23:20:45 +00:00
feat: Implement Doc-Sync engine for automated multi-language documentation
This commit is contained in:
thePR0M3TH3AN committed
1 parent
3968b679a6
commit
12c4e00ece
18 files changed
+722
No files matched your search
@@ -4,6 +4,18 @@ Generate printable flyers with QR codes linking to Tor (.onion) hidden services,
|
||||
|
||||
---
|
||||
|
||||
## Documentation
|
||||
|
||||
VoxVera is available in multiple languages. Select your preferred language for the detailed usage guide:
|
||||
|
||||
| Language | Documentation |
|
||||
| :--- | :--- |
|
||||
| 🇺🇸 **English** | [docs/en/usage.md](docs/en/usage.md) |
|
||||
| 🇪🇸 **Español** | [docs/es/usage.md](docs/es/usage.md) |
|
||||
| 🇩🇪 **Deutsch** | [docs/de/usage.md](docs/de/usage.md) |
|
||||
|
||||
---
|
||||
|
||||
## Key Features
|
||||
|
||||
* **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.
|
||||
|
||||
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
@@ -0,0 +1,16 @@
|
||||
# Docker Usage
|
||||
|
||||
A prebuilt image containing Tor, OnionShare and the `voxvera` CLI is published to
|
||||
`ghcr.io/voxvera/voxvera`.
|
||||
|
||||
```bash
|
||||
# pull the image
|
||||
docker pull ghcr.io/voxvera/voxvera:latest
|
||||
|
||||
# run voxvera quickstart with flyers stored in ./flyers
|
||||
mkdir -p flyers
|
||||
docker run -it --rm -v "$(pwd)/flyers:/flyers" ghcr.io/voxvera/voxvera
|
||||
```
|
||||
|
||||
The container uses `/flyers` as the working directory and runs `voxvera quickstart`
|
||||
by default. All generated flyer files will appear in the mounted `flyers` folder.
|
||||
@@ -0,0 +1,14 @@
|
||||
# Flyer Templates
|
||||
|
||||
Pre-built flyer templates live in the `templates/` directory. Use the CLI to copy one with:
|
||||
|
||||
```bash
|
||||
voxvera init --template <name>
|
||||
```
|
||||
|
||||
This will create a new folder under `dist/` named `<name>-<YYYYMMDD>` containing the template files.
|
||||
|
||||
Available templates:
|
||||
|
||||
- **blank** – minimal placeholder files, also used when extracting fields from a PDF.
|
||||
- **voxvera** – example flyer showcasing the VoxVera project.
|
||||
@@ -0,0 +1,60 @@
|
||||
# Troubleshooting
|
||||
|
||||
This page collects common issues encountered when hosting or accessing flyers.
|
||||
|
||||
## Tor connectivity
|
||||
- Ensure Tor is allowed through your firewall. On systems using `ufw` you may need to run `sudo ufw allow tor`.
|
||||
- Some networks block Tor entirely. If you cannot reach onion services, try connecting over a different network or use a Tor bridge.
|
||||
|
||||
## Tor port detection
|
||||
|
||||
`voxvera serve` auto-detects Tor by probing common ports (9050/9150 for SOCKS, 9051/9151 for control). If detection fails -- for example when Tor runs on non-standard ports -- you can override with environment variables:
|
||||
|
||||
```bash
|
||||
TOR_SOCKS_PORT=19050 TOR_CONTROL_PORT=19051 voxvera serve
|
||||
```
|
||||
|
||||
If no running Tor is found, the defaults (9050/9051) are used and OnionShare will attempt to connect on those ports.
|
||||
|
||||
## Firewall rules
|
||||
- If `voxvera serve` fails to start OnionShare, verify that outbound connections on ports 9001 and 80 are permitted.
|
||||
- Corporate or university firewalls can block the hidden service ports required by Tor.
|
||||
|
||||
## SELinux
|
||||
- On SELinux-enabled distributions you may see `permission denied` errors when OnionShare writes to the `host` directory.
|
||||
- Run `sudo chcon -Rt svirt_sandbox_file_t host` or disable SELinux enforcement for the folder.
|
||||
|
||||
## OnionShare crashes
|
||||
If `voxvera serve` prints "OnionShare exited unexpectedly", check the log file
|
||||
`host/<folder_name>/onionshare.log` for details. Common causes:
|
||||
|
||||
- Tor is not running (`sudo systemctl start tor`)
|
||||
- A port conflict with another service
|
||||
- Missing `onionshare-cli` (run `voxvera check`)
|
||||
|
||||
## Onion URL changed unexpectedly
|
||||
The onion URL is tied to the Ed25519 keypair stored in
|
||||
`host/<folder_name>/.onionshare-session`. If this file is deleted, a new
|
||||
keypair (and URL) will be generated on the next `voxvera serve`. The
|
||||
`voxvera import` command preserves this file automatically, but manual
|
||||
deletion of the `host/` directory will destroy it.
|
||||
|
||||
## QR codes not generated
|
||||
If `voxvera build` reports "No URLs configured yet", this is expected before the first `voxvera serve`. QR codes for tear-off links are generated automatically once the .onion address is known. QR codes for the content link are generated if you provided a URL during `voxvera init`.
|
||||
|
||||
## Electron GUI
|
||||
If `npm start` fails with `spawn voxvera ENOENT`, the `voxvera` command is not in your `PATH`. Install it with `pipx install git+https://github.com/PR0M3TH3AN/VoxVera.git` or run `./install.sh` from the repository.
|
||||
|
||||
## Missing dependencies
|
||||
Run `voxvera check` to verify your setup. The command checks for required
|
||||
Python packages (`qrcode`, `Pillow`, `jsmin`, `htmlmin`, `pypdf`) and
|
||||
external tools (`onionshare-cli`), then prints a summary of anything
|
||||
missing. To install everything:
|
||||
|
||||
```bash
|
||||
# Recommended: use the install script (handles Tor + OnionShare too)
|
||||
curl -fsSL https://raw.githubusercontent.com/PR0M3TH3AN/VoxVera/main/install.sh | bash
|
||||
|
||||
# Or reinstall just the Python package
|
||||
pipx install --force 'voxvera@git+https://github.com/PR0M3TH3AN/VoxVera.git@main'
|
||||
```
|
||||
@@ -0,0 +1,130 @@
|
||||
# Detailed Usage
|
||||
|
||||
This guide covers common CLI workflows. See `docs/docker.md` for Docker instructions and `docs/templates.md` for available flyer templates.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
VoxVera is designed to be highly portable and requires minimal system dependencies.
|
||||
|
||||
### 1. Standalone Binaries (Recommended)
|
||||
You can download standalone, zero-dependency binaries for your operating system:
|
||||
- **Linux:** `voxvera-linux`
|
||||
- **Windows:** `voxvera-windows.exe`
|
||||
- **macOS:** `voxvera-macos`
|
||||
|
||||
These binaries include everything needed to run VoxVera (except `onionshare-cli`).
|
||||
|
||||
### 2. One-Line Installer
|
||||
Alternatively, install via our automated script:
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/PR0M3TH3AN/VoxVera/main/install.sh | bash
|
||||
```
|
||||
|
||||
### 3. Manual Python Install
|
||||
If you prefer to run from source:
|
||||
|
||||
```bash
|
||||
pipx install 'voxvera@git+https://github.com/PR0M3TH3AN/VoxVera.git@main'
|
||||
sudo apt install tor onionshare-cli # Debian/Ubuntu
|
||||
```
|
||||
|
||||
## Step-by-Step
|
||||
|
||||
1. **Initialize:** Run `voxvera init` and follow the prompts. You will be asked to select your language first.
|
||||
2. **Build:** Generate the flyer assets. Every build automatically creates a `voxvera-portable.zip` in the flyer's folder, allowing others to download the full tool directly from your flyer.
|
||||
```bash
|
||||
voxvera build
|
||||
```
|
||||
3. **Serve:** Publish the flyer over Tor:
|
||||
```bash
|
||||
voxvera serve
|
||||
```
|
||||
This automatically detects your Tor instance, starts OnionShare, and writes the generated .onion address into the flyer's tear-off links.
|
||||
|
||||
## Language Support
|
||||
|
||||
VoxVera is fully localized. You can change your language preference permanently using either the interactive selector or a direct shortcut:
|
||||
|
||||
- **Interactive Selector:** `voxvera lang`
|
||||
- **Direct Shortcut:** `voxvera --lang de` (sets preference to German)
|
||||
|
||||
### Supported Languages:
|
||||
- **English:** `en`
|
||||
- **Spanish:** `es` (alias: `--idioma`)
|
||||
- **German:** `de` (alias: `--sprache`)
|
||||
|
||||
You can also force a specific language for a single command without changing your permanent preference:
|
||||
- **English:** `voxvera --lang en check`
|
||||
- **German:** `voxvera --sprache de check`
|
||||
- **Spanish:** `voxvera --idioma es check`
|
||||
|
||||
The generated flyers automatically detect the visitor's browser language and switch the UI text accordingly.
|
||||
|
||||
## Server Management
|
||||
|
||||
Manage multiple flyers and their Tor identities from a single interactive menu:
|
||||
|
||||
```bash
|
||||
voxvera manage
|
||||
```
|
||||
|
||||
Features:
|
||||
- **--- Create New Site/Flyer ---**: Start the full setup sequence.
|
||||
- **Start/Stop All Sites**: Launch or shut down every flyer in your fleet at once.
|
||||
- **Real-time Status**: View active `.onion` URLs and Tor bootstrapping progress indicators.
|
||||
- **Individual Control**: Export specific sites to ZIP or delete them.
|
||||
|
||||
## Universal Mirroring (Viral Distribution)
|
||||
|
||||
To ensure VoxVera remains accessible even if central repositories are censored, every flyer acts as a mirror for the tool.
|
||||
|
||||
When you host a flyer, the **"Download Tool & Source"** button on the landing page provides a `voxvera-portable.zip` containing:
|
||||
- The full source code and all supported languages.
|
||||
- All Python dependencies (pre-vendored).
|
||||
- Cross-platform Tor binaries.
|
||||
|
||||
This allows anyone who scans your flyer to become a new distributor of the VoxVera tool.
|
||||
|
||||
## Export & Backup
|
||||
|
||||
Back up your unique Tor identities (so your `.onion` URL never changes) or move your flyers to another machine.
|
||||
|
||||
- **Export a single site**: `voxvera export <folder_name>`
|
||||
- **Export all sites**: `voxvera export-all`
|
||||
|
||||
**Storage location:** All exports are saved to `~/voxvera-exports/` on all platforms.
|
||||
|
||||
## Import & Recovery
|
||||
|
||||
Restore your entire setup on a new machine by moving your ZIP files to `~/voxvera-exports/` and running:
|
||||
|
||||
```bash
|
||||
voxvera import-multiple
|
||||
```
|
||||
|
||||
## Portability & Offline Use
|
||||
|
||||
If you need to run VoxVera on a machine without internet access, you can "vendorize" the dependencies first:
|
||||
|
||||
```bash
|
||||
voxvera vendorize
|
||||
```
|
||||
|
||||
This downloads all required Python libraries into `voxvera/vendor/`. The tool will then prioritize these local files, allowing it to run without `pip install`.
|
||||
|
||||
## Batch Import (JSON)
|
||||
|
||||
To bulk-generate flyers from multiple JSON configuration files, place them in the `imports/` directory and run:
|
||||
|
||||
```bash
|
||||
voxvera batch-import
|
||||
```
|
||||
|
||||
## How URLs Work
|
||||
|
||||
Each flyer has two separate URLs:
|
||||
- **Tear-off link** (auto-generated): The .onion address where the flyer is hosted.
|
||||
- **Content link** (user-configured): An external URL pointing to a website, video, or download.
|
||||
|
||||
You do not need to manually enter the .onion address; VoxVera handles this automatically during the `serve` phase.
|
||||
@@ -0,0 +1,16 @@
|
||||
# Docker Usage
|
||||
|
||||
A prebuilt image containing Tor, OnionShare and the `voxvera` CLI is published to
|
||||
`ghcr.io/voxvera/voxvera`.
|
||||
|
||||
```bash
|
||||
# pull the image
|
||||
docker pull ghcr.io/voxvera/voxvera:latest
|
||||
|
||||
# run voxvera quickstart with flyers stored in ./flyers
|
||||
mkdir -p flyers
|
||||
docker run -it --rm -v "$(pwd)/flyers:/flyers" ghcr.io/voxvera/voxvera
|
||||
```
|
||||
|
||||
The container uses `/flyers` as the working directory and runs `voxvera quickstart`
|
||||
by default. All generated flyer files will appear in the mounted `flyers` folder.
|
||||
@@ -0,0 +1,14 @@
|
||||
# Flyer Templates
|
||||
|
||||
Pre-built flyer templates live in the `templates/` directory. Use the CLI to copy one with:
|
||||
|
||||
```bash
|
||||
voxvera init --template <name>
|
||||
```
|
||||
|
||||
This will create a new folder under `dist/` named `<name>-<YYYYMMDD>` containing the template files.
|
||||
|
||||
Available templates:
|
||||
|
||||
- **blank** – minimal placeholder files, also used when extracting fields from a PDF.
|
||||
- **voxvera** – example flyer showcasing the VoxVera project.
|
||||
@@ -0,0 +1,60 @@
|
||||
# Troubleshooting
|
||||
|
||||
This page collects common issues encountered when hosting or accessing flyers.
|
||||
|
||||
## Tor connectivity
|
||||
- Ensure Tor is allowed through your firewall. On systems using `ufw` you may need to run `sudo ufw allow tor`.
|
||||
- Some networks block Tor entirely. If you cannot reach onion services, try connecting over a different network or use a Tor bridge.
|
||||
|
||||
## Tor port detection
|
||||
|
||||
`voxvera serve` auto-detects Tor by probing common ports (9050/9150 for SOCKS, 9051/9151 for control). If detection fails -- for example when Tor runs on non-standard ports -- you can override with environment variables:
|
||||
|
||||
```bash
|
||||
TOR_SOCKS_PORT=19050 TOR_CONTROL_PORT=19051 voxvera serve
|
||||
```
|
||||
|
||||
If no running Tor is found, the defaults (9050/9051) are used and OnionShare will attempt to connect on those ports.
|
||||
|
||||
## Firewall rules
|
||||
- If `voxvera serve` fails to start OnionShare, verify that outbound connections on ports 9001 and 80 are permitted.
|
||||
- Corporate or university firewalls can block the hidden service ports required by Tor.
|
||||
|
||||
## SELinux
|
||||
- On SELinux-enabled distributions you may see `permission denied` errors when OnionShare writes to the `host` directory.
|
||||
- Run `sudo chcon -Rt svirt_sandbox_file_t host` or disable SELinux enforcement for the folder.
|
||||
|
||||
## OnionShare crashes
|
||||
If `voxvera serve` prints "OnionShare exited unexpectedly", check the log file
|
||||
`host/<folder_name>/onionshare.log` for details. Common causes:
|
||||
|
||||
- Tor is not running (`sudo systemctl start tor`)
|
||||
- A port conflict with another service
|
||||
- Missing `onionshare-cli` (run `voxvera check`)
|
||||
|
||||
## Onion URL changed unexpectedly
|
||||
The onion URL is tied to the Ed25519 keypair stored in
|
||||
`host/<folder_name>/.onionshare-session`. If this file is deleted, a new
|
||||
keypair (and URL) will be generated on the next `voxvera serve`. The
|
||||
`voxvera import` command preserves this file automatically, but manual
|
||||
deletion of the `host/` directory will destroy it.
|
||||
|
||||
## QR codes not generated
|
||||
If `voxvera build` reports "No URLs configured yet", this is expected before the first `voxvera serve`. QR codes for tear-off links are generated automatically once the .onion address is known. QR codes for the content link are generated if you provided a URL during `voxvera init`.
|
||||
|
||||
## Electron GUI
|
||||
If `npm start` fails with `spawn voxvera ENOENT`, the `voxvera` command is not in your `PATH`. Install it with `pipx install git+https://github.com/PR0M3TH3AN/VoxVera.git` or run `./install.sh` from the repository.
|
||||
|
||||
## Missing dependencies
|
||||
Run `voxvera check` to verify your setup. The command checks for required
|
||||
Python packages (`qrcode`, `Pillow`, `jsmin`, `htmlmin`, `pypdf`) and
|
||||
external tools (`onionshare-cli`), then prints a summary of anything
|
||||
missing. To install everything:
|
||||
|
||||
```bash
|
||||
# Recommended: use the install script (handles Tor + OnionShare too)
|
||||
curl -fsSL https://raw.githubusercontent.com/PR0M3TH3AN/VoxVera/main/install.sh | bash
|
||||
|
||||
# Or reinstall just the Python package
|
||||
pipx install --force 'voxvera@git+https://github.com/PR0M3TH3AN/VoxVera.git@main'
|
||||
```
|
||||
@@ -0,0 +1,130 @@
|
||||
# Detailed Usage
|
||||
|
||||
This guide covers common CLI workflows. See `docs/docker.md` for Docker instructions and `docs/templates.md` for available flyer templates.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
VoxVera is designed to be highly portable and requires minimal system dependencies.
|
||||
|
||||
### 1. Standalone Binaries (Recommended)
|
||||
You can download standalone, zero-dependency binaries for your operating system:
|
||||
- **Linux:** `voxvera-linux`
|
||||
- **Windows:** `voxvera-windows.exe`
|
||||
- **macOS:** `voxvera-macos`
|
||||
|
||||
These binaries include everything needed to run VoxVera (except `onionshare-cli`).
|
||||
|
||||
### 2. One-Line Installer
|
||||
Alternatively, install via our automated script:
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/PR0M3TH3AN/VoxVera/main/install.sh | bash
|
||||
```
|
||||
|
||||
### 3. Manual Python Install
|
||||
If you prefer to run from source:
|
||||
|
||||
```bash
|
||||
pipx install 'voxvera@git+https://github.com/PR0M3TH3AN/VoxVera.git@main'
|
||||
sudo apt install tor onionshare-cli # Debian/Ubuntu
|
||||
```
|
||||
|
||||
## Step-by-Step
|
||||
|
||||
1. **Initialize:** Run `voxvera init` and follow the prompts. You will be asked to select your language first.
|
||||
2. **Build:** Generate the flyer assets. Every build automatically creates a `voxvera-portable.zip` in the flyer's folder, allowing others to download the full tool directly from your flyer.
|
||||
```bash
|
||||
voxvera build
|
||||
```
|
||||
3. **Serve:** Publish the flyer over Tor:
|
||||
```bash
|
||||
voxvera serve
|
||||
```
|
||||
This automatically detects your Tor instance, starts OnionShare, and writes the generated .onion address into the flyer's tear-off links.
|
||||
|
||||
## Language Support
|
||||
|
||||
VoxVera is fully localized. You can change your language preference permanently using either the interactive selector or a direct shortcut:
|
||||
|
||||
- **Interactive Selector:** `voxvera lang`
|
||||
- **Direct Shortcut:** `voxvera --lang de` (sets preference to German)
|
||||
|
||||
### Supported Languages:
|
||||
- **English:** `en`
|
||||
- **Spanish:** `es` (alias: `--idioma`)
|
||||
- **German:** `de` (alias: `--sprache`)
|
||||
|
||||
You can also force a specific language for a single command without changing your permanent preference:
|
||||
- **English:** `voxvera --lang en check`
|
||||
- **German:** `voxvera --sprache de check`
|
||||
- **Spanish:** `voxvera --idioma es check`
|
||||
|
||||
The generated flyers automatically detect the visitor's browser language and switch the UI text accordingly.
|
||||
|
||||
## Server Management
|
||||
|
||||
Manage multiple flyers and their Tor identities from a single interactive menu:
|
||||
|
||||
```bash
|
||||
voxvera manage
|
||||
```
|
||||
|
||||
Features:
|
||||
- **--- Create New Site/Flyer ---**: Start the full setup sequence.
|
||||
- **Start/Stop All Sites**: Launch or shut down every flyer in your fleet at once.
|
||||
- **Real-time Status**: View active `.onion` URLs and Tor bootstrapping progress indicators.
|
||||
- **Individual Control**: Export specific sites to ZIP or delete them.
|
||||
|
||||
## Universal Mirroring (Viral Distribution)
|
||||
|
||||
To ensure VoxVera remains accessible even if central repositories are censored, every flyer acts as a mirror for the tool.
|
||||
|
||||
When you host a flyer, the **"Download Tool & Source"** button on the landing page provides a `voxvera-portable.zip` containing:
|
||||
- The full source code and all supported languages.
|
||||
- All Python dependencies (pre-vendored).
|
||||
- Cross-platform Tor binaries.
|
||||
|
||||
This allows anyone who scans your flyer to become a new distributor of the VoxVera tool.
|
||||
|
||||
## Export & Backup
|
||||
|
||||
Back up your unique Tor identities (so your `.onion` URL never changes) or move your flyers to another machine.
|
||||
|
||||
- **Export a single site**: `voxvera export <folder_name>`
|
||||
- **Export all sites**: `voxvera export-all`
|
||||
|
||||
**Storage location:** All exports are saved to `~/voxvera-exports/` on all platforms.
|
||||
|
||||
## Import & Recovery
|
||||
|
||||
Restore your entire setup on a new machine by moving your ZIP files to `~/voxvera-exports/` and running:
|
||||
|
||||
```bash
|
||||
voxvera import-multiple
|
||||
```
|
||||
|
||||
## Portability & Offline Use
|
||||
|
||||
If you need to run VoxVera on a machine without internet access, you can "vendorize" the dependencies first:
|
||||
|
||||
```bash
|
||||
voxvera vendorize
|
||||
```
|
||||
|
||||
This downloads all required Python libraries into `voxvera/vendor/`. The tool will then prioritize these local files, allowing it to run without `pip install`.
|
||||
|
||||
## Batch Import (JSON)
|
||||
|
||||
To bulk-generate flyers from multiple JSON configuration files, place them in the `imports/` directory and run:
|
||||
|
||||
```bash
|
||||
voxvera batch-import
|
||||
```
|
||||
|
||||
## How URLs Work
|
||||
|
||||
Each flyer has two separate URLs:
|
||||
- **Tear-off link** (auto-generated): The .onion address where the flyer is hosted.
|
||||
- **Content link** (user-configured): An external URL pointing to a website, video, or download.
|
||||
|
||||
You do not need to manually enter the .onion address; VoxVera handles this automatically during the `serve` phase.
|
||||
Vendored
+16
@@ -0,0 +1,16 @@
|
||||
# Docker Usage
|
||||
|
||||
A prebuilt image containing Tor, OnionShare and the `voxvera` CLI is published to
|
||||
`ghcr.io/voxvera/voxvera`.
|
||||
|
||||
```bash
|
||||
# pull the image
|
||||
docker pull ghcr.io/voxvera/voxvera:latest
|
||||
|
||||
# run voxvera quickstart with flyers stored in ./flyers
|
||||
mkdir -p flyers
|
||||
docker run -it --rm -v "$(pwd)/flyers:/flyers" ghcr.io/voxvera/voxvera
|
||||
```
|
||||
|
||||
The container uses `/flyers` as the working directory and runs `voxvera quickstart`
|
||||
by default. All generated flyer files will appear in the mounted `flyers` folder.
|
||||
Vendored
+14
@@ -0,0 +1,14 @@
|
||||
# Flyer Templates
|
||||
|
||||
Pre-built flyer templates live in the `templates/` directory. Use the CLI to copy one with:
|
||||
|
||||
```bash
|
||||
voxvera init --template <name>
|
||||
```
|
||||
|
||||
This will create a new folder under `dist/` named `<name>-<YYYYMMDD>` containing the template files.
|
||||
|
||||
Available templates:
|
||||
|
||||
- **blank** – minimal placeholder files, also used when extracting fields from a PDF.
|
||||
- **voxvera** – example flyer showcasing the VoxVera project.
|
||||
Vendored
+60
@@ -0,0 +1,60 @@
|
||||
# Troubleshooting
|
||||
|
||||
This page collects common issues encountered when hosting or accessing flyers.
|
||||
|
||||
## Tor connectivity
|
||||
- Ensure Tor is allowed through your firewall. On systems using `ufw` you may need to run `sudo ufw allow tor`.
|
||||
- Some networks block Tor entirely. If you cannot reach onion services, try connecting over a different network or use a Tor bridge.
|
||||
|
||||
## Tor port detection
|
||||
|
||||
`voxvera serve` auto-detects Tor by probing common ports (9050/9150 for SOCKS, 9051/9151 for control). If detection fails -- for example when Tor runs on non-standard ports -- you can override with environment variables:
|
||||
|
||||
```bash
|
||||
TOR_SOCKS_PORT=19050 TOR_CONTROL_PORT=19051 voxvera serve
|
||||
```
|
||||
|
||||
If no running Tor is found, the defaults (9050/9051) are used and OnionShare will attempt to connect on those ports.
|
||||
|
||||
## Firewall rules
|
||||
- If `voxvera serve` fails to start OnionShare, verify that outbound connections on ports 9001 and 80 are permitted.
|
||||
- Corporate or university firewalls can block the hidden service ports required by Tor.
|
||||
|
||||
## SELinux
|
||||
- On SELinux-enabled distributions you may see `permission denied` errors when OnionShare writes to the `host` directory.
|
||||
- Run `sudo chcon -Rt svirt_sandbox_file_t host` or disable SELinux enforcement for the folder.
|
||||
|
||||
## OnionShare crashes
|
||||
If `voxvera serve` prints "OnionShare exited unexpectedly", check the log file
|
||||
`host/<folder_name>/onionshare.log` for details. Common causes:
|
||||
|
||||
- Tor is not running (`sudo systemctl start tor`)
|
||||
- A port conflict with another service
|
||||
- Missing `onionshare-cli` (run `voxvera check`)
|
||||
|
||||
## Onion URL changed unexpectedly
|
||||
The onion URL is tied to the Ed25519 keypair stored in
|
||||
`host/<folder_name>/.onionshare-session`. If this file is deleted, a new
|
||||
keypair (and URL) will be generated on the next `voxvera serve`. The
|
||||
`voxvera import` command preserves this file automatically, but manual
|
||||
deletion of the `host/` directory will destroy it.
|
||||
|
||||
## QR codes not generated
|
||||
If `voxvera build` reports "No URLs configured yet", this is expected before the first `voxvera serve`. QR codes for tear-off links are generated automatically once the .onion address is known. QR codes for the content link are generated if you provided a URL during `voxvera init`.
|
||||
|
||||
## Electron GUI
|
||||
If `npm start` fails with `spawn voxvera ENOENT`, the `voxvera` command is not in your `PATH`. Install it with `pipx install git+https://github.com/PR0M3TH3AN/VoxVera.git` or run `./install.sh` from the repository.
|
||||
|
||||
## Missing dependencies
|
||||
Run `voxvera check` to verify your setup. The command checks for required
|
||||
Python packages (`qrcode`, `Pillow`, `jsmin`, `htmlmin`, `pypdf`) and
|
||||
external tools (`onionshare-cli`), then prints a summary of anything
|
||||
missing. To install everything:
|
||||
|
||||
```bash
|
||||
# Recommended: use the install script (handles Tor + OnionShare too)
|
||||
curl -fsSL https://raw.githubusercontent.com/PR0M3TH3AN/VoxVera/main/install.sh | bash
|
||||
|
||||
# Or reinstall just the Python package
|
||||
pipx install --force 'voxvera@git+https://github.com/PR0M3TH3AN/VoxVera.git@main'
|
||||
```
|
||||
Vendored
+130
@@ -0,0 +1,130 @@
|
||||
# Detailed Usage
|
||||
|
||||
This guide covers common CLI workflows. See `docs/docker.md` for Docker instructions and `docs/templates.md` for available flyer templates.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
VoxVera is designed to be highly portable and requires minimal system dependencies.
|
||||
|
||||
### 1. Standalone Binaries (Recommended)
|
||||
You can download standalone, zero-dependency binaries for your operating system:
|
||||
- **Linux:** `voxvera-linux`
|
||||
- **Windows:** `voxvera-windows.exe`
|
||||
- **macOS:** `voxvera-macos`
|
||||
|
||||
These binaries include everything needed to run VoxVera (except `onionshare-cli`).
|
||||
|
||||
### 2. One-Line Installer
|
||||
Alternatively, install via our automated script:
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/PR0M3TH3AN/VoxVera/main/install.sh | bash
|
||||
```
|
||||
|
||||
### 3. Manual Python Install
|
||||
If you prefer to run from source:
|
||||
|
||||
```bash
|
||||
pipx install 'voxvera@git+https://github.com/PR0M3TH3AN/VoxVera.git@main'
|
||||
sudo apt install tor onionshare-cli # Debian/Ubuntu
|
||||
```
|
||||
|
||||
## Step-by-Step
|
||||
|
||||
1. **Initialize:** Run `voxvera init` and follow the prompts. You will be asked to select your language first.
|
||||
2. **Build:** Generate the flyer assets. Every build automatically creates a `voxvera-portable.zip` in the flyer's folder, allowing others to download the full tool directly from your flyer.
|
||||
```bash
|
||||
voxvera build
|
||||
```
|
||||
3. **Serve:** Publish the flyer over Tor:
|
||||
```bash
|
||||
voxvera serve
|
||||
```
|
||||
This automatically detects your Tor instance, starts OnionShare, and writes the generated .onion address into the flyer's tear-off links.
|
||||
|
||||
## Language Support
|
||||
|
||||
VoxVera is fully localized. You can change your language preference permanently using either the interactive selector or a direct shortcut:
|
||||
|
||||
- **Interactive Selector:** `voxvera lang`
|
||||
- **Direct Shortcut:** `voxvera --lang de` (sets preference to German)
|
||||
|
||||
### Supported Languages:
|
||||
- **English:** `en`
|
||||
- **Spanish:** `es` (alias: `--idioma`)
|
||||
- **German:** `de` (alias: `--sprache`)
|
||||
|
||||
You can also force a specific language for a single command without changing your permanent preference:
|
||||
- **English:** `voxvera --lang en check`
|
||||
- **German:** `voxvera --sprache de check`
|
||||
- **Spanish:** `voxvera --idioma es check`
|
||||
|
||||
The generated flyers automatically detect the visitor's browser language and switch the UI text accordingly.
|
||||
|
||||
## Server Management
|
||||
|
||||
Manage multiple flyers and their Tor identities from a single interactive menu:
|
||||
|
||||
```bash
|
||||
voxvera manage
|
||||
```
|
||||
|
||||
Features:
|
||||
- **--- Create New Site/Flyer ---**: Start the full setup sequence.
|
||||
- **Start/Stop All Sites**: Launch or shut down every flyer in your fleet at once.
|
||||
- **Real-time Status**: View active `.onion` URLs and Tor bootstrapping progress indicators.
|
||||
- **Individual Control**: Export specific sites to ZIP or delete them.
|
||||
|
||||
## Universal Mirroring (Viral Distribution)
|
||||
|
||||
To ensure VoxVera remains accessible even if central repositories are censored, every flyer acts as a mirror for the tool.
|
||||
|
||||
When you host a flyer, the **"Download Tool & Source"** button on the landing page provides a `voxvera-portable.zip` containing:
|
||||
- The full source code and all supported languages.
|
||||
- All Python dependencies (pre-vendored).
|
||||
- Cross-platform Tor binaries.
|
||||
|
||||
This allows anyone who scans your flyer to become a new distributor of the VoxVera tool.
|
||||
|
||||
## Export & Backup
|
||||
|
||||
Back up your unique Tor identities (so your `.onion` URL never changes) or move your flyers to another machine.
|
||||
|
||||
- **Export a single site**: `voxvera export <folder_name>`
|
||||
- **Export all sites**: `voxvera export-all`
|
||||
|
||||
**Storage location:** All exports are saved to `~/voxvera-exports/` on all platforms.
|
||||
|
||||
## Import & Recovery
|
||||
|
||||
Restore your entire setup on a new machine by moving your ZIP files to `~/voxvera-exports/` and running:
|
||||
|
||||
```bash
|
||||
voxvera import-multiple
|
||||
```
|
||||
|
||||
## Portability & Offline Use
|
||||
|
||||
If you need to run VoxVera on a machine without internet access, you can "vendorize" the dependencies first:
|
||||
|
||||
```bash
|
||||
voxvera vendorize
|
||||
```
|
||||
|
||||
This downloads all required Python libraries into `voxvera/vendor/`. The tool will then prioritize these local files, allowing it to run without `pip install`.
|
||||
|
||||
## Batch Import (JSON)
|
||||
|
||||
To bulk-generate flyers from multiple JSON configuration files, place them in the `imports/` directory and run:
|
||||
|
||||
```bash
|
||||
voxvera batch-import
|
||||
```
|
||||
|
||||
## How URLs Work
|
||||
|
||||
Each flyer has two separate URLs:
|
||||
- **Tear-off link** (auto-generated): The .onion address where the flyer is hosted.
|
||||
- **Content link** (user-configured): An external URL pointing to a website, video, or download.
|
||||
|
||||
You do not need to manually enter the .onion address; VoxVera handles this automatically during the `serve` phase.
|
||||
@@ -652,6 +652,53 @@ def import_multiple_sites(source_dir: str = None):
|
||||
print("\nImport multiple complete.")
|
||||
|
||||
|
||||
def build_docs():
|
||||
"""Generate localized documentation from templates and locale data."""
|
||||
template_dir = ROOT.parent / "docs" / "templates"
|
||||
if not template_dir.exists():
|
||||
print("Error: docs/templates/ not found.")
|
||||
return
|
||||
|
||||
# List all supported languages
|
||||
locale_files = sorted(glob.glob(str(ROOT / "locales" / "*.json")))
|
||||
langs = [Path(f).stem for f in locale_files]
|
||||
|
||||
for lang in langs:
|
||||
print(f"Generating documentation for: {lang}")
|
||||
load_locale(lang)
|
||||
dest_dir = ROOT.parent / "docs" / lang
|
||||
os.makedirs(dest_dir, exist_ok=True)
|
||||
|
||||
# Process each template
|
||||
for t_file in glob.glob(str(template_dir / "*.md")):
|
||||
name = Path(t_file).name
|
||||
with open(t_file, "r", encoding="utf-8") as f:
|
||||
content = f.read()
|
||||
|
||||
# Replace tokens: {{t('path.to.token')}}
|
||||
# This regex looks for {{t('...')}} and {{t("...")}}
|
||||
import re as _re
|
||||
|
||||
def replace_token(match):
|
||||
token_path = match.group(1)
|
||||
return t(token_path)
|
||||
|
||||
content = _re.sub(r"\{\{t\(['\"](.+?)['\"]\)\}\}", replace_token, content)
|
||||
|
||||
# Look for localized overrides in voxvera/locales/{lang}/docs/{name}
|
||||
override_path = ROOT / "locales" / lang / "docs" / name
|
||||
if override_path.exists():
|
||||
with open(override_path, "r", encoding="utf-8") as f:
|
||||
content = f.read()
|
||||
# Process tokens in the override as well
|
||||
content = _re.sub(r"\{\{t\(['\"](.+?)['\"]\)\}\}", replace_token, content)
|
||||
|
||||
with open(dest_dir / name, "w", encoding="utf-8") as f:
|
||||
f.write(content)
|
||||
|
||||
print("Documentation build complete.")
|
||||
|
||||
|
||||
def vendorize():
|
||||
"""Download all dependencies into voxvera/vendor/ for portable use."""
|
||||
vendor_dir = ROOT / "vendor"
|
||||
@@ -970,6 +1017,7 @@ def main(argv=None):
|
||||
)
|
||||
sub.add_parser("check", help="Check for required external dependencies")
|
||||
sub.add_parser("vendorize", help="Download all dependencies into voxvera/vendor/ for portability")
|
||||
sub.add_parser("build-docs", help="Generate localized documentation from templates")
|
||||
sub.add_parser("manage", help="Manage VoxVera servers interactively")
|
||||
|
||||
args = parser.parse_args(argv)
|
||||
@@ -1056,6 +1104,8 @@ def main(argv=None):
|
||||
check_deps()
|
||||
elif args.command == "vendorize":
|
||||
vendorize()
|
||||
elif args.command == "build-docs":
|
||||
build_docs()
|
||||
else:
|
||||
parser.print_help()
|
||||
|
||||
|
||||
Reference in new issue
Block a user