mirror of
https://github.com/PR0M3TH3AN/VoxVera.git
synced 2026-10-27 09:40:40 +00:00
131 lines
4.6 KiB
Markdown
131 lines
4.6 KiB
Markdown
# 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.
|