Self-hosted, fast, lightweight Matrix server powered by Conduit (Rust)

📖 Persian Version (نسخه فارسی)

• Features
• Quick Start
• Installation
• User Guide
• Admin Panel
• Voice/Video Calls
• Custom Port
• Troubleshooting
• FAQ
• Contributing
• License

Requirements:

• Ubuntu 20.04+ or Debian 11+
• 2GB RAM minimum
• Domain name (or IP address)
• Ports: 80, 443 (or custom), 3478, 5349 (UDP)

One-line installation:

git clone https://github.com/MatinSenPai/zanjir.git ~/zanjir
cd ~/zanjir
sudo bash install.sh

Access:

• Web App: https://your-domain.com
• Admin Panel: https://your-domain.com/admin

git clone https://github.com/MatinSenPai/zanjir.git
cd zanjir

sudo bash install.sh

Installation prompts:

1. Server address - Your domain or IP (e.g., matrix.example.com or 185.123.45.67)
2. Admin email - For SSL certificates (domain mode only)
3. HTTPS port - Default: 443 (press Enter), or custom (e.g., 8443)

After installation completes:

docker exec -it zanjir-dendrite /usr/bin/create-account \
    --config /etc/dendrite/dendrite.yaml \
    --username YOUR_USERNAME \
    --admin

Example:

docker exec -it zanjir-dendrite /usr/bin/create-account \
    --config /etc/dendrite/dendrite.yaml \
    --username admin \
    --admin

You'll be prompted to set a password.

After installation, use the zanjir command to manage your server:

zanjir

zanjir              # Interactive menu
zanjir status       # Show service status
zanjir logs         # View logs (all services)
zanjir logs conduit # View specific service logs
zanjir restart      # Restart all services
zanjir start        # Start all services
zanjir stop         # Stop all services
zanjir update       # Update to latest version
zanjir backup       # Backup all data
zanjir uninstall    # Completely remove Zanjir

When you run zanjir without arguments, you'll see a beautiful interactive menu:

╔═══════════════════════════╗
║                           ║
║      Z A N J I R ⛓️       ║
║                           ║
╚═══════════════════════════╝

Matrix Server Management Tool
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Main Menu:

  1. Show Status
  2. View Logs
  3. Restart Services
  4. Start Services
  5. Stop Services
  6. Update Zanjir
  7. Backup Data
  8. Uninstall
  9. Exit

1. Visit https://your-domain.com
2. Click "Create account"
3. Fill in username and password
4. Start messaging!

• Create Room: Click + button → New Room
• Invite Users: Room settings → Invite users → Enter @username:your-domain.com
• Send Messages: Type and press Enter
• Voice Call: Click phone icon in room header
• Video Call: Click video icon in room header

Android:

• Element (Play Store)
• Element (F-Droid)

iOS:

• Element (App Store)

Configuration:

• Homeserver URL: https://your-domain.com
• Identity server: Leave blank

Visit: https://your-domain.com/admin

Login with your admin account credentials.

• Total users count
• Active users
• Total rooms

• View all users
• Disable user accounts
• Delete users
• View user status

• Track all admin actions
• Timestamps and IP addresses
• Target user tracking
• Detailed action logs

Disable a user:

1. Go to Users page
2. Find user
3. Click "Disable"

Delete a user:

1. Go to Users page
2. Find user
3. Click "Delete" → Confirm

All actions are automatically logged and visible in the Logs page.

Zanjir includes a TURN server (coturn) for reliable voice/video calls.

TURN server helps users behind NAT/firewalls connect:

• Direct P2P when possible
• TURN relay when necessary
• Automatic fallback

Required ports:

UFW example:

sudo ufw allow 3478/udp
sudo ufw allow 5349/udp

1. Create two accounts
2. Create a room, invite both users
3. Click phone/video icon
4. Accept call on other end

If port 443 is already in use, you can use a custom port.

During install.sh, enter your desired port:

HTTPS port (default: 443): 8443

This will:

• Use port 8443 for HTTPS
• Use port 8080 for HTTP (auto-calculated)
• Update all configurations

https://your-domain.com:8443

1. Edit .env:

   nano .env

2. Change HTTPS_PORT and HTTP_PORT
3. Restart services:

   docker compose down
   docker compose up -d

Error: connection refused to download.docker.com

Solution: Script automatically uses Iranian mirrors:

• docker.arvancloud.ir
• registry.docker.ir

Check:

1. Verify registration is enabled in docker-compose.yml: CONDUIT_ALLOW_REGISTRATION: "true"
2. Check element-config.json: "UIFeature.registration": true
3. Restart containers:

   docker compose restart

Solutions:

1. Check TURN server is running:

   docker ps | grep coturn

2. Verify firewall allows UDP 3478, 5349
3. Check TURN secret in .env matches TURN_SECRET environment variable

Solutions:

1. Verify user is admin:

   docker exec -it zanjir-dendrite /usr/bin/create-account \
       --config /etc/dendrite/dendrite.yaml \
       --username YOUR_USERNAME \
       --admin

2. Check admin container logs:

   docker logs zanjir-admin

Solution: Use custom port during installation, or change port in .env

Q: Can I use an IP address instead of domain?
A: Yes! The installer detects IP mode and uses self-signed certificates.

Q: Is federation enabled?
A: No, Zanjir is designed for isolated single-server deployment.

Q: Can users video call externally?
A: Only within your Zanjir server (federation disabled).

Q: How are passwords stored?
A: Bcrypt hashed in PostgreSQL.

Q: Is end-to-end encryption supported?
A: Yes! Element/Matrix supports E2EE by default.

Q: What about audit logs?
A: Admin actions logged in SQLite (admin/audit_log.db).

Q: How many users can it handle?
A: Conduit is extremely lightweight. A 1GB VPS can handle ~100-500 users with ease. Conduit uses ~50MB RAM vs Dendrite's 200-500MB.

Q: What about backups?
A: Backup Docker volumes:

docker run --rm \
  -v zanjir-postgres-data:/data \
  -v $(pwd):/backup \
  ubuntu tar czf /backup/postgres-backup.tar.gz /data

Contributions welcome! Please:

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open Pull Request

MIT License - see LICENSE file

• Matrix.org - Open protocol
• Conduit - Fast, lightweight Rust homeserver
• Element - Web client
• Coturn - TURN server
• Caddy - Reverse proxy

• GitHub Issues: Report bugs
• Discussions: Ask questions

Made with ❤️ for secure, private communication