Codakey
Play
← Back to HelloZeroNet/ZeroNet

How to Deploy & Use HelloZeroNet/ZeroNet

ZeroNet Deployment and Usage Guide

Prerequisites

System Requirements

  • Operating System: Windows, macOS, or Linux (x86-64bit)
  • Python: Python 3.x (for source installation)
  • Network: Internet connection for initial setup and peer discovery
  • Ports: Port 43110 (default) must be accessible for incoming connections

Optional Dependencies

  • Tor: For anonymous browsing and .onion hidden service support
  • Docker: For containerized deployment
  • Android: Android 16 (JellyBean) or higher for mobile usage

Installation

Quick Install (Recommended)

Windows

# Download and run the pre-built executable
# 1. Download ZeroNet-py3-win64.zip from GitHub releases
# 2. Unpack to any location
# 3. Run ZeroNet.exe

macOS

# Download and run the pre-built application
# 1. Download ZeroNet-dist-mac.zip from GitHub releases
# 2. Unpack to any location
# 3. Run ZeroNet.app

Linux (x86-64bit)

# Download and extract the pre-built package
wget https://github.com/HelloZeroNet/ZeroNet-linux/archive/dist-linux64/ZeroNet-py3-linux64.tar.gz
tar xvpfz ZeroNet-py3-linux64.tar.gz
cd ZeroNet-linux-dist-linux64/
./ZeroNet.sh

Android

Docker Installation

# Pull and run the official Docker image
docker pull nofish/zeronet
docker run -p 43110:43110 nofish/zeronet

Source Installation

# Clone the repository
git clone https://github.com/HelloZeroNet/ZeroNet.git
cd ZeroNet

# Install Python dependencies
sudo apt-get update
sudo apt-get install python3-pip
sudo python3 -m pip install -r requirements.txt

# Start ZeroNet
python3 zeronet.py

Configuration

Environment Variables

  • UI_IP: Set to '*' to allow remote connections to the web interface
  • UI_RESTRICT: Restrict remote connections to specific IP addresses (e.g., your.ip.address)

Configuration Files

ZeroNet automatically creates configuration files in the data directory. No manual configuration is typically required for basic usage.

Network Configuration

  • Port: Default is 43110, can be changed in settings
  • UPnP: Automatic port opening enabled by default
  • Tor: Optional for anonymous browsing (requires Tor installation)

Build & Run

Local Development

# Start ZeroNet with web interface on localhost
python3 zeronet.py

# Start with remote access enabled
python3 zeronet.py --ui_ip '*' --ui_restrict your.ip.address

# Access the ZeroHello landing page
# Open http://127.0.0.1:43110/ in your browser

Production Usage

# Use the pre-built executables for production
# Windows: Run ZeroNet.exe
# macOS: Run ZeroNet.app
# Linux: Run ./ZeroNet.sh

# For headless servers, use Docker
docker run -d -p 43110:43110 nofish/zeronet

Deployment

Platform Recommendations

Docker (Recommended for Production)

# Deploy using Docker Compose
version: '3'
services:
  zeronet:
    image: nofish/zeronet
    ports:
      - "43110:43110"
    restart: unless-stopped

VPS/Cloud Servers

  • DigitalOcean: Ubuntu 20.04+ droplets
  • AWS EC2: t2.micro or larger instances
  • Vultr: Any Linux VPS with 1GB RAM minimum

Self-Hosted

  • Raspberry Pi: Works well with ARM builds
  • Home Server: Any machine with 24/7 connectivity

Network Considerations

  • Ensure port 43110 is open on your firewall
  • Consider using Tor for enhanced privacy
  • For public sites, ensure adequate bandwidth for serving content

Troubleshooting

Common Issues

Port Already in Use

# Check what's using port 43110
sudo lsof -i :43110

# Kill the process or change ZeroNet's port
python3 zeronet.py --ui_port 43111

Connection Issues

  • Problem: Cannot connect to peers
  • Solution: Check firewall settings, ensure port 43110 is open, verify internet connectivity

Performance Issues

  • Problem: Slow site loading
  • Solution: Increase bandwidth, reduce concurrent connections, use SSD storage

Tor Not Working

  • Problem: Tor hidden services not accessible
  • Solution: Install Tor separately, verify Tor service is running

Site Creation Issues

  • Problem: Cannot create new sites
  • Solution: Ensure you have sufficient disk space, check permissions on data directory

Debug Mode

# Start with verbose logging
python3 zeronet.py --debug

# Check logs for specific errors
tail -f ~/.zeronet/debug.log

Community Support

← Project overviewView alternatives to HelloZeroNet/ZeroNet →