# Installation Guide
How to build, install, and run V-Queue.
## Prerequisites
### System Requirements
- **Operating System**: Linux, macOS, or Windows
- **Disk Space**: Minimum 100MB for binaries, plus storage for queue data
- **Memory**: Minimum 512MB RAM
- **CPU**: Any modern CPU (no special requirements)
### Software Requirements
- **Rust**: Version 1.56 or higher (Rust 2021 edition)
- **Cargo**: Comes with Rust installation
- **Git**: For cloning the repository
## Quick Start
### 1. Install Rust
If you don't have Rust installed:
```bash
```
Verify installation:
```bash
rustc --version
cargo --version
```
### 2. Clone Repository
```bash
git clone https://github.com/semantic-machines/v-queue.git
cd v-queue
```
### 3. Build Core Library
```bash
cargo build --release
```
This creates the core library at `target/release/libv_queue.so` (or `.dylib` on macOS, `.dll` on Windows).
### 4. Build and Run Server
```bash
cd v-queue-server
cargo build --release
```
Run with default settings:
```bash
./target/release/v-queue-server
```
Or run directly with cargo:
```bash
cargo run --release
```
### 5. Verify Server is Running
```bash
curl http://localhost:9093/health
```
Expected response:
```json
{
"status": "ok",
"version": "0.1.0"
}
```
## Installation Options
### Option 1: Run from Source
Best for development and testing:
```bash
cd v-queue-server
cargo run --release -- --bind 0.0.0.0:9093 --data-dir ./queues
```
### Option 2: Install Binary
Install to system path:
```bash
cd v-queue-server
cargo install --path .
```
This installs to `~/.cargo/bin/v-queue-server`.
Then run from anywhere:
```bash
v-queue-server --bind 0.0.0.0:9093 --data-dir /var/lib/vqueue
```
### Option 3: Copy Binary
Copy the binary to desired location:
```bash
cd v-queue-server
cargo build --release
sudo cp target/release/v-queue-server /usr/local/bin/
```
Run:
```bash
v-queue-server --config /etc/vqueue/server.toml
```
## Configuration
### Create Configuration File
On first run, a default configuration file is created:
```bash
v-queue-server
# Creates v-queue-server.toml in current directory
```
Edit the configuration:
```toml
# Server bind address
bind_address = "127.0.0.1:9093"
# Data storage directory
data_directory = "./queues"
# Logging level: debug, info, warn, error
log_level = "info"
# Maximum message size (bytes)
max_message_size = 1048576
# Default batch size
default_batch_size = 100
# Authentication
auth_enabled = false
# User accounts (when auth enabled)
[users]
admin = "changeme"
```
### Command-Line Options
Override config file settings:
```bash
v-queue-server --help
```
```
A network server for v-queue message queue
Usage: v-queue-server [OPTIONS]
Options:
-b, --bind <BIND> Override bind address
-d, --data-dir <DATA_DIR> Override data directory
-l, --log-level <LOG_LEVEL> Override log level
--no-auth Disable authentication
-c, --config <CONFIG> Path to config file [default: v-queue-server.toml]
-h, --help Print help
```
### Examples
Run on all interfaces:
```bash
v-queue-server --bind 0.0.0.0:9093
```
Custom data directory:
```bash
v-queue-server --data-dir /var/lib/vqueue/data
```
Enable debug logging:
```bash
v-queue-server --log-level debug
```
Disable authentication:
```bash
v-queue-server --no-auth
```
Use custom config:
```bash
v-queue-server --config /etc/vqueue/production.toml
```
## Running as a Service
### systemd Service (Linux)
Create `/etc/systemd/system/v-queue-server.service`:
```ini
[Unit]
Description=V-Queue Message Queue Server
After=network.target
[Service]
Type=simple
User=vqueue
Group=vqueue
WorkingDirectory=/var/lib/vqueue
ExecStart=/usr/local/bin/v-queue-server --config /etc/vqueue/server.toml
Restart=on-failure
RestartSec=5s
# Security
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/lib/vqueue
[Install]
WantedBy=multi-user.target
```
Create user and directories:
```bash
sudo useradd -r -s /bin/false vqueue
sudo mkdir -p /var/lib/vqueue/queues
sudo mkdir -p /etc/vqueue
sudo chown -R vqueue:vqueue /var/lib/vqueue
```
Copy config file:
```bash
sudo cp v-queue-server.toml /etc/vqueue/server.toml
sudo chown vqueue:vqueue /etc/vqueue/server.toml
```
Enable and start:
```bash
sudo systemctl daemon-reload
sudo systemctl enable v-queue-server
sudo systemctl start v-queue-server
```
Check status:
```bash
sudo systemctl status v-queue-server
sudo journalctl -u v-queue-server -f
```
### Docker Container
Create `Dockerfile`:
```dockerfile
FROM rust:1.70 as builder
WORKDIR /build
COPY . .
RUN cd v-queue-server && cargo build --release
FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y \
ca-certificates \
&& rm -rf /var/lib/apt/lists/*
COPY --from=builder /build/v-queue-server/target/release/v-queue-server /usr/local/bin/
RUN useradd -r -s /bin/false vqueue && \
mkdir -p /var/lib/vqueue/queues && \
chown -R vqueue:vqueue /var/lib/vqueue
USER vqueue
WORKDIR /var/lib/vqueue
EXPOSE 9093
CMD ["v-queue-server", "--bind", "0.0.0.0:9093", "--data-dir", "/var/lib/vqueue/queues", "--no-auth"]
```
Build and run:
```bash
docker build -t v-queue-server .
docker run -d -p 9093:9093 -v /path/to/data:/var/lib/vqueue/queues v-queue-server
```
### Docker Compose
Create `docker-compose.yml`:
```yaml
version: '3.8'
services:
v-queue:
build: .
ports:
- "9093:9093"
volumes:
- ./queues:/var/lib/vqueue/queues
- ./v-queue-server.toml:/etc/vqueue/server.toml
command: ["v-queue-server", "--config", "/etc/vqueue/server.toml"]
restart: unless-stopped
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:9093/health"]
interval: 30s
timeout: 3s
retries: 3
```
Run:
```bash
docker-compose up -d
```
## Data Directory Structure
After running, the data directory will look like:
```
queues/
├── events_info_queue # Queue metadata
├── events_queue.lock # Write lock
└── events-0/ # Partition 0
├── events_queue # Message data
└── events_info_push # Write position
```
Consumer data is also stored here:
```
queues/
├── events_info_pop_my-consumer # Consumer offset tracking
└── ...
```
## Backup and Migration
### Backup
Simply copy the entire data directory:
```bash
cp -r /var/lib/vqueue/queues /backup/vqueue-$(date +%Y%m%d)
```
For live backups, ensure consumers are paused to maintain consistency.
### Restore
Copy the backup to the data directory:
```bash
cp -r /backup/vqueue-20240101/queues /var/lib/vqueue/
chown -R vqueue:vqueue /var/lib/vqueue/queues
```
Restart the server:
```bash
sudo systemctl restart v-queue-server
```
### Migration
To move to a different server:
1. Stop the old server
2. Copy data directory to new server
3. Install v-queue-server on new server
4. Start new server pointing to copied data
5. Update client configurations
## Troubleshooting
### Server won't start
Check port availability:
```bash
Check permissions:
```bash
ls -la /var/lib/vqueue
```
Check logs:
```bash
v-queue-server --log-level debug
```
### Permission denied errors
Ensure data directory is writable:
```bash
sudo chown -R vqueue:vqueue /var/lib/vqueue
sudo chmod -R 755 /var/lib/vqueue
```
### Cannot bind to port
Use a different port or run as root (not recommended):
```bash
v-queue-server --bind 127.0.0.1:9094
```
Or allow binding to privileged ports:
```bash
sudo setcap 'cap_net_bind_service=+ep' /usr/local/bin/v-queue-server
```
## Uninstallation
### Remove binary
```bash
sudo rm /usr/local/bin/v-queue-server
```
Or if installed via cargo:
```bash
cargo uninstall v-queue-server
```
### Remove service
```bash
sudo systemctl stop v-queue-server
sudo systemctl disable v-queue-server
sudo rm /etc/systemd/system/v-queue-server.service
sudo systemctl daemon-reload
```
### Remove data
```bash
sudo rm -rf /var/lib/vqueue
sudo rm -rf /etc/vqueue
sudo userdel vqueue
```
## Next Steps
- [Configuration Guide](04-configuration.md)
- [API Reference](05-api-reference.md)
- [Client Examples](07-client-examples.md)