mirror of
https://github.com/PR0M3TH3AN/VoxVera.git
synced 2026-10-27 09:40:40 +00:00
feat: Add support for Russian, Hebrew (RTL), and Arabic (RTL) with visual width validation
This commit is contained in:
thePR0M3TH3AN committed
1 parent
6afbe29552
commit
ece805a6d2
25 files changed
+1297
-10
No files matched your search
@@ -0,0 +1,41 @@
|
||||
# AI Agent Instructions for VoxVera
|
||||
|
||||
This guide is for AI agents (like Gemini, Claude, or GPT) contributing to the VoxVera project. Follow these protocols to maintain the architectural integrity and multi-language support.
|
||||
|
||||
## Core Mandates
|
||||
|
||||
1. **Security-First**: VoxVera is a Tor-based tool. Never suggest features that leak IP addresses or use non-Tor external resources (CDNs, etc.).
|
||||
2. **Local-First**: All assets (fonts, dependencies, binaries) must be self-contained within the `voxvera/` package to support the Universal Mirroring model.
|
||||
3. **Tokenized UI**: Never hardcode user-facing strings. Always add them to `voxvera/locales/en.json` and use the `t('cli.token')` helper.
|
||||
4. **Markdown Redaction**: Use `~~text~~` in locale JSONs for strike-through effects. Both the build system and the JS engine handle the conversion to `<span class="redacted">` automatically.
|
||||
|
||||
## Localization Protocol
|
||||
|
||||
When adding a new language or updating an existing one:
|
||||
- **CLI/Flyers**: Update `voxvera/locales/{lang}.json`. Include `meta`, `cli`, `web`, and `landing` categories.
|
||||
- **Landing Page**:
|
||||
- Directly update the `const locales` object in `site/index.html`.
|
||||
- **Crucial**: Run `voxvera build-site` to generate the latest portable bundle and refresh the pre-rendered HTML.
|
||||
- **Documentation**:
|
||||
- Master templates live in `docs/templates/`.
|
||||
- Localized overrides live in `voxvera/locales/{lang}/docs/`.
|
||||
- **Crucial**: After any change to locales or templates, you MUST run `voxvera build-docs` to synchronize the output in `docs/{en,es,de}/`.
|
||||
|
||||
## Universal Mirroring
|
||||
|
||||
VoxVera propagates through its own flyers.
|
||||
- Every `voxvera build` and `voxvera build-site` generates `voxvera-portable.zip`.
|
||||
- If you modify the core source code, ensure the `bundle_portable` function in `voxvera/cli.py` still correctly captures all necessary directories (especially `vendor/`, `locales/`, and `resources/`).
|
||||
|
||||
## Verification Checklist
|
||||
|
||||
Before finishing a task, ensure you have:
|
||||
1. Run unit tests: `pytest tests/test_cli.py`.
|
||||
2. Verified the localization: `voxvera --lang {lang} check`.
|
||||
3. Rebuilt the documentation: `voxvera build-docs`.
|
||||
4. Synchronized the public site: `voxvera build-site`.
|
||||
5. Verified the portable bundle exists: `ls -l voxvera/host/*/download/voxvera-portable.zip` and `ls -l site/download/voxvera-portable.zip`.
|
||||
|
||||
---
|
||||
|
||||
Follow these rules to ensure VoxVera remains a robust, viral, and decentralized tool for truth.
|
||||
@@ -0,0 +1,42 @@
|
||||
# Contributing to VoxVera
|
||||
|
||||
Thank you for your interest in contributing to VoxVera! This project aims to be a global, censorship-resistant tool, and your help—especially with translations—is vital.
|
||||
|
||||
## Adding a New Language
|
||||
|
||||
VoxVera uses a centralized token system for the CLI and Web components, and a template-based system for Documentation. To add a new language (e.g., French/`fr`), follow this checklist:
|
||||
|
||||
### 1. The Token File
|
||||
Create a new JSON file in `voxvera/locales/{lang_code}.json`.
|
||||
- Use `en.json` as your master template.
|
||||
- **`meta`**: Include the native language name and a flag emoji.
|
||||
- **`cli`**: Translate all strings used in the terminal interface.
|
||||
- **`web`**: Translate strings used on the generated landing pages and flyers.
|
||||
- **`landing`**: Translate the specific content for the official VoxVera website.
|
||||
- **Formatting**: You can use Markdown-style strike-throughs (`~~redacted text~~`) in any of these strings; they will be automatically converted to the stylized "redacted" effect on the flyers.
|
||||
|
||||
### 2. The Landing Page
|
||||
The main landing page (`site/index.html`) must be synchronized to include your new language.
|
||||
- Open `site/index.html` and add your language to the `const locales` object in the `<script>` tag.
|
||||
- Run `voxvera build-site` to refresh the public assets and ensure the pre-rendered HTML matches your new locale.
|
||||
|
||||
### 3. Documentation
|
||||
VoxVera uses the **Doc-Sync Engine** to keep manuals in sync.
|
||||
- Create localized Markdown files in `voxvera/locales/{lang_code}/docs/`.
|
||||
- Use the templates in `docs/templates/` as your guide.
|
||||
- You can use `cli.token_name` to reference terminal commands automatically.
|
||||
|
||||
### 4. Build and Verify
|
||||
Run the following commands to verify your changes:
|
||||
- `voxvera --lang {lang_code} check` (Verify CLI translation)
|
||||
- `voxvera build-docs` (Generate localized manuals)
|
||||
- Open `site/index.html` in a browser and test the language switcher.
|
||||
|
||||
## Code Contributions
|
||||
- Ensure all tests pass: `pytest tests/test_cli.py`.
|
||||
- Follow the existing coding style (PEP 8 for Python).
|
||||
- If adding a new feature, update the master templates in `docs/templates/` and run `voxvera build-docs`.
|
||||
|
||||
---
|
||||
|
||||
Together, we can ensure that truth remains accessible to everyone, everywhere.
|
||||
@@ -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:
|
||||
- **--- إنشاء موقع/منشور جديد ---**: Start the full setup sequence.
|
||||
- **--- تشغيل جميع المواقع ---**: 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**: تصدير إلى Zip 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 **"تحميل الأداة والكود"** 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,41 @@
|
||||
# AI Agent Instructions for VoxVera
|
||||
|
||||
This guide is for AI agents (like Gemini, Claude, or GPT) contributing to the VoxVera project. Follow these protocols to maintain the architectural integrity and multi-language support.
|
||||
|
||||
## Core Mandates
|
||||
|
||||
1. **Security-First**: VoxVera is a Tor-based tool. Never suggest features that leak IP addresses or use non-Tor external resources (CDNs, etc.).
|
||||
2. **Local-First**: All assets (fonts, dependencies, binaries) must be self-contained within the `voxvera/` package to support the Universal Mirroring model.
|
||||
3. **Tokenized UI**: Never hardcode user-facing strings. Always add them to `voxvera/locales/en.json` and use the `t('cli.token')` helper.
|
||||
4. **Markdown Redaction**: Use `~~text~~` in locale JSONs for strike-through effects. Both the build system and the JS engine handle the conversion to `<span class="redacted">` automatically.
|
||||
|
||||
## Localization Protocol
|
||||
|
||||
When adding a new language or updating an existing one:
|
||||
- **CLI/Flyers**: Update `voxvera/locales/{lang}.json`. Include `meta`, `cli`, `web`, and `landing` categories.
|
||||
- **Landing Page**:
|
||||
- Directly update the `const locales` object in `site/index.html`.
|
||||
- **Crucial**: Run `voxvera build-site` to generate the latest portable bundle and refresh the pre-rendered HTML.
|
||||
- **Documentation**:
|
||||
- Master templates live in `docs/templates/`.
|
||||
- Localized overrides live in `voxvera/locales/{lang}/docs/`.
|
||||
- **Crucial**: After any change to locales or templates, you MUST run `voxvera build-docs` to synchronize the output in `docs/{en,es,de}/`.
|
||||
|
||||
## Universal Mirroring
|
||||
|
||||
VoxVera propagates through its own flyers.
|
||||
- Every `voxvera build` and `voxvera build-site` generates `voxvera-portable.zip`.
|
||||
- If you modify the core source code, ensure the `bundle_portable` function in `voxvera/cli.py` still correctly captures all necessary directories (especially `vendor/`, `locales/`, and `resources/`).
|
||||
|
||||
## Verification Checklist
|
||||
|
||||
Before finishing a task, ensure you have:
|
||||
1. Run unit tests: `pytest tests/test_cli.py`.
|
||||
2. Verified the localization: `voxvera --lang {lang} check`.
|
||||
3. Rebuilt the documentation: `voxvera build-docs`.
|
||||
4. Synchronized the public site: `voxvera build-site`.
|
||||
5. Verified the portable bundle exists: `ls -l voxvera/host/*/download/voxvera-portable.zip` and `ls -l site/download/voxvera-portable.zip`.
|
||||
|
||||
---
|
||||
|
||||
Follow these rules to ensure VoxVera remains a robust, viral, and decentralized tool for truth.
|
||||
@@ -0,0 +1,42 @@
|
||||
# Contributing to VoxVera
|
||||
|
||||
Thank you for your interest in contributing to VoxVera! This project aims to be a global, censorship-resistant tool, and your help—especially with translations—is vital.
|
||||
|
||||
## Adding a New Language
|
||||
|
||||
VoxVera uses a centralized token system for the CLI and Web components, and a template-based system for Documentation. To add a new language (e.g., French/`fr`), follow this checklist:
|
||||
|
||||
### 1. The Token File
|
||||
Create a new JSON file in `voxvera/locales/{lang_code}.json`.
|
||||
- Use `en.json` as your master template.
|
||||
- **`meta`**: Include the native language name and a flag emoji.
|
||||
- **`cli`**: Translate all strings used in the terminal interface.
|
||||
- **`web`**: Translate strings used on the generated landing pages and flyers.
|
||||
- **`landing`**: Translate the specific content for the official VoxVera website.
|
||||
- **Formatting**: You can use Markdown-style strike-throughs (`~~redacted text~~`) in any of these strings; they will be automatically converted to the stylized "redacted" effect on the flyers.
|
||||
|
||||
### 2. The Landing Page
|
||||
The main landing page (`site/index.html`) must be synchronized to include your new language.
|
||||
- Open `site/index.html` and add your language to the `const locales` object in the `<script>` tag.
|
||||
- Run `voxvera build-site` to refresh the public assets and ensure the pre-rendered HTML matches your new locale.
|
||||
|
||||
### 3. Documentation
|
||||
VoxVera uses the **Doc-Sync Engine** to keep manuals in sync.
|
||||
- Create localized Markdown files in `voxvera/locales/{lang_code}/docs/`.
|
||||
- Use the templates in `docs/templates/` as your guide.
|
||||
- You can use `cli.token_name` to reference terminal commands automatically.
|
||||
|
||||
### 4. Build and Verify
|
||||
Run the following commands to verify your changes:
|
||||
- `voxvera --lang {lang_code} check` (Verify CLI translation)
|
||||
- `voxvera build-docs` (Generate localized manuals)
|
||||
- Open `site/index.html` in a browser and test the language switcher.
|
||||
|
||||
## Code Contributions
|
||||
- Ensure all tests pass: `pytest tests/test_cli.py`.
|
||||
- Follow the existing coding style (PEP 8 for Python).
|
||||
- If adding a new feature, update the master templates in `docs/templates/` and run `voxvera build-docs`.
|
||||
|
||||
---
|
||||
|
||||
Together, we can ensure that truth remains accessible to everyone, everywhere.
|
||||
@@ -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:
|
||||
- **--- צור אתר/פלייר חדש ---**: Start the full setup sequence.
|
||||
- **--- הפעל את כל האתרים ---**: 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**: ייצא ל-Zip 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 **"הורד כלי וקוד מקור"** 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,41 @@
|
||||
# AI Agent Instructions for VoxVera
|
||||
|
||||
This guide is for AI agents (like Gemini, Claude, or GPT) contributing to the VoxVera project. Follow these protocols to maintain the architectural integrity and multi-language support.
|
||||
|
||||
## Core Mandates
|
||||
|
||||
1. **Security-First**: VoxVera is a Tor-based tool. Never suggest features that leak IP addresses or use non-Tor external resources (CDNs, etc.).
|
||||
2. **Local-First**: All assets (fonts, dependencies, binaries) must be self-contained within the `voxvera/` package to support the Universal Mirroring model.
|
||||
3. **Tokenized UI**: Never hardcode user-facing strings. Always add them to `voxvera/locales/en.json` and use the `t('cli.token')` helper.
|
||||
4. **Markdown Redaction**: Use `~~text~~` in locale JSONs for strike-through effects. Both the build system and the JS engine handle the conversion to `<span class="redacted">` automatically.
|
||||
|
||||
## Localization Protocol
|
||||
|
||||
When adding a new language or updating an existing one:
|
||||
- **CLI/Flyers**: Update `voxvera/locales/{lang}.json`. Include `meta`, `cli`, `web`, and `landing` categories.
|
||||
- **Landing Page**:
|
||||
- Directly update the `const locales` object in `site/index.html`.
|
||||
- **Crucial**: Run `voxvera build-site` to generate the latest portable bundle and refresh the pre-rendered HTML.
|
||||
- **Documentation**:
|
||||
- Master templates live in `docs/templates/`.
|
||||
- Localized overrides live in `voxvera/locales/{lang}/docs/`.
|
||||
- **Crucial**: After any change to locales or templates, you MUST run `voxvera build-docs` to synchronize the output in `docs/{en,es,de}/`.
|
||||
|
||||
## Universal Mirroring
|
||||
|
||||
VoxVera propagates through its own flyers.
|
||||
- Every `voxvera build` and `voxvera build-site` generates `voxvera-portable.zip`.
|
||||
- If you modify the core source code, ensure the `bundle_portable` function in `voxvera/cli.py` still correctly captures all necessary directories (especially `vendor/`, `locales/`, and `resources/`).
|
||||
|
||||
## Verification Checklist
|
||||
|
||||
Before finishing a task, ensure you have:
|
||||
1. Run unit tests: `pytest tests/test_cli.py`.
|
||||
2. Verified the localization: `voxvera --lang {lang} check`.
|
||||
3. Rebuilt the documentation: `voxvera build-docs`.
|
||||
4. Synchronized the public site: `voxvera build-site`.
|
||||
5. Verified the portable bundle exists: `ls -l voxvera/host/*/download/voxvera-portable.zip` and `ls -l site/download/voxvera-portable.zip`.
|
||||
|
||||
---
|
||||
|
||||
Follow these rules to ensure VoxVera remains a robust, viral, and decentralized tool for truth.
|
||||
@@ -0,0 +1,42 @@
|
||||
# Contributing to VoxVera
|
||||
|
||||
Thank you for your interest in contributing to VoxVera! This project aims to be a global, censorship-resistant tool, and your help—especially with translations—is vital.
|
||||
|
||||
## Adding a New Language
|
||||
|
||||
VoxVera uses a centralized token system for the CLI and Web components, and a template-based system for Documentation. To add a new language (e.g., French/`fr`), follow this checklist:
|
||||
|
||||
### 1. The Token File
|
||||
Create a new JSON file in `voxvera/locales/{lang_code}.json`.
|
||||
- Use `en.json` as your master template.
|
||||
- **`meta`**: Include the native language name and a flag emoji.
|
||||
- **`cli`**: Translate all strings used in the terminal interface.
|
||||
- **`web`**: Translate strings used on the generated landing pages and flyers.
|
||||
- **`landing`**: Translate the specific content for the official VoxVera website.
|
||||
- **Formatting**: You can use Markdown-style strike-throughs (`~~redacted text~~`) in any of these strings; they will be automatically converted to the stylized "redacted" effect on the flyers.
|
||||
|
||||
### 2. The Landing Page
|
||||
The main landing page (`site/index.html`) must be synchronized to include your new language.
|
||||
- Open `site/index.html` and add your language to the `const locales` object in the `<script>` tag.
|
||||
- Run `voxvera build-site` to refresh the public assets and ensure the pre-rendered HTML matches your new locale.
|
||||
|
||||
### 3. Documentation
|
||||
VoxVera uses the **Doc-Sync Engine** to keep manuals in sync.
|
||||
- Create localized Markdown files in `voxvera/locales/{lang_code}/docs/`.
|
||||
- Use the templates in `docs/templates/` as your guide.
|
||||
- You can use `cli.token_name` to reference terminal commands automatically.
|
||||
|
||||
### 4. Build and Verify
|
||||
Run the following commands to verify your changes:
|
||||
- `voxvera --lang {lang_code} check` (Verify CLI translation)
|
||||
- `voxvera build-docs` (Generate localized manuals)
|
||||
- Open `site/index.html` in a browser and test the language switcher.
|
||||
|
||||
## Code Contributions
|
||||
- Ensure all tests pass: `pytest tests/test_cli.py`.
|
||||
- Follow the existing coding style (PEP 8 for Python).
|
||||
- If adding a new feature, update the master templates in `docs/templates/` and run `voxvera build-docs`.
|
||||
|
||||
---
|
||||
|
||||
Together, we can ensure that truth remains accessible to everyone, everywhere.
|
||||
@@ -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:
|
||||
- **--- Создать новый сайт/листовку ---**: Start the full setup sequence.
|
||||
- **--- Запустить все сайты ---**: 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**: Экспорт в Zip 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 **"Скачать инструмент и код"** 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.
|
||||
Reference in new issue
Block a user