Troubleshooting

Troubleshooting

Common issues and solutions for Cloudillo installation and operation.

Installation Issues

Docker: “Cannot connect to Docker daemon”

Symptoms: Error when running docker run or docker-compose

Cause: Docker service not running

Solutions:

# Start Docker service
sudo systemctl start docker
sudo systemctl enable docker

# Verify Docker is running
docker ps

Docker: “Port 443 already in use”

Symptoms: Container fails to start with port binding error

Cause: Another service is using port 443 (or 80)

Solutions:

1. Find what’s using the port:

sudo lsof -i :443
sudo lsof -i :80

2. Stop the conflicting service:

# For nginx
sudo systemctl stop nginx

# For Apache
sudo systemctl stop apache2

3. Or use Proxy Mode instead of Standalone Mode (see install-yourself)

Build: “Rust compiler version too old”

Symptoms: Build fails with compiler version error

Cause: Rust 1.70+ required

Solution:

# Update Rust
rustup update stable
rustup default stable

# Verify version
rustc --version  # Should show 1.70.0 or higher

Build: Compilation errors

Symptoms: cargo build fails with errors

Possible Causes & Solutions:

1. Outdated dependencies:

cargo clean
cargo update
cargo build --release

2. Missing system libraries:

# On Ubuntu/Debian
sudo apt update
sudo apt install build-essential pkg-config libssl-dev

# On macOS
xcode-select --install

3. Corrupted cache:

rm -rf ~/.cargo/registry
rm -rf ~/.cargo/git
cargo build --release

DNS and Domain Issues

DNS records not propagating

Symptoms: Can’t access Cloudillo at your domain

Cause: DNS changes take time to propagate globally

Solutions:

1. Check DNS records:

dig yourdomain.com A
dig cl-o.yourdomain.com A

# Or use online tools
# https://dnschecker.org

2. Reduce TTL before making changes (set to 300 seconds)

3. Wait: DNS propagation can take 24-48 hours

4. Use local hosts file for testing:

# Add to /etc/hosts (Linux/Mac) or C:\Windows\System32\drivers\etc\hosts (Windows)
203.0.113.42  yourdomain.com
203.0.113.42  cl-o.yourdomain.com

Let’s Encrypt certificate issuance fails

Symptoms: ACME certificate challenge fails

Possible Causes & Solutions:

1. DNS not yet propagated - Wait and retry

2. Port 80 not accessible:

# Test from external server
nc -zv yourdomain.com 80

# Check firewall
sudo ufw status
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

3. Wrong DNS records:

# Verify both domains point to correct IP
dig yourdomain.com A
dig cl-o.yourdomain.com A

4. Rate limiting - Let’s Encrypt has limits (5 certificates per domain per week)

Runtime Issues

Can’t login / Authentication fails

Symptoms: Login page shows error or wrong credentials message

Possible Causes & Solutions:

1. Wrong credentials:

   • Check BASE_PASSWORD environment variable
   • Default password should have been changed

2. Database corruption:

# Check logs for database errors
docker logs cloudillo

# Or for built version
journalctl -u cloudillo -n 100

3. Clock skew - JWT tokens are time-sensitive:

# Sync system time
sudo timedatectl set-ntp true

# Or manually
sudo ntpdate pool.ntp.org

File upload fails

Symptoms: File upload returns error or times out

Possible Causes:

1. File size exceeds limit:

   • Check server logs for exact error
   • Increase limits in reverse proxy if using one

2. Disk full:

# Check disk space
df -h

# Check data directory specifically
du -sh /var/vol/cloudillo/*

3. Handler not yet implemented - Check Status Page to verify file upload is working in current version

4. Permissions:

# Verify data directory permissions
ls -la /var/vol/cloudillo

# Fix if needed
sudo chown -R 1000:1000 /var/vol/cloudillo

WebSocket connection fails

Symptoms: Real-time features don’t work, connection errors in browser console

Possible Causes & Solutions:

1. Reverse proxy not configured for WebSocket:

# nginx configuration needed
location /ws {
    proxy_pass http://localhost:1443;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "Upgrade";
    proxy_set_header Host $host;
}

2. Firewall blocking WebSocket:

# Allow WebSocket traffic (usually over HTTPS)
sudo ufw allow 443/tcp

3. Feature not yet implemented - Check Status Page for RTDB/CRDT status

API endpoint returns 404 or errors

Symptoms: API calls fail with 404 or unexpected errors

Cause: Endpoint not yet implemented in Rust version (Phase 1 only 20% complete)

Solution:

1. Check Status Page for endpoint status
2. Use only ✅ Working endpoints
3. Wait for Phase 2 (Q1 2025) for full API coverage
4. Monitor Development Status for updates

Performance Issues

High memory usage

Symptoms: Server using more RAM than expected

Possible Causes & Solutions:

1. Large number of concurrent connections:

   • Expected for many users
   • Increase server RAM
   • Implement rate limiting

2. Memory leak - Report issue:

# Get memory usage over time
ps aux | grep cloudillo

# Check for memory leaks with valgrind (if available)

Slow response times

Symptoms: API calls take long to complete

Possible Causes:

1. Database size - SQLite performance degrades with large databases:

   • Consider vacuuming: sqlite3 /data/priv/meta.db "VACUUM;"
   • Monitor database size

2. High load:

# Check CPU usage
top

# Check I/O wait
iostat -x 1

3. Network latency - If behind reverse proxy:
   • Check proxy logs
   • Test direct connection (if safe)

Debugging Tips

Enable verbose logging

For Docker:

docker logs -f cloudillo

For systemd service:

journalctl -u cloudillo -f

For built version:

# Set RUST_LOG environment variable
export RUST_LOG=debug
./target/release/cloudillo-basic-server

Check server health

# Test basic connectivity
curl -I https://yourdomain.com

# Test API endpoint
curl -X GET https://yourdomain.com/api/me/keys

# Test WebSocket (requires wscat)
npm install -g wscat
wscat -c wss://yourdomain.com/ws/bus

Browser developer tools

1. Open DevTools (F12)
2. Check Console for JavaScript errors
3. Check Network tab for failed requests
4. Check Application → Storage for quota issues

Verify database integrity

# Check SQLite databases
sqlite3 /var/vol/cloudillo/priv/auth.db "PRAGMA integrity_check;"
sqlite3 /var/vol/cloudillo/priv/meta.db "PRAGMA integrity_check;"

# Check redb databases (RTDB/CRDT)
# Use database-specific tools or check logs for corruption messages

Getting Help

Before asking for help

Gather this information:

1. Version: Rust v0.1.0-alpha or Node.js v0.9.x (deprecated)?
2. Installation method: Docker, built from source, or other?
3. Operating system: Linux distro, macOS, Windows?
4. Error messages: Full error text from logs
5. Reproduction steps: What did you do before the error?
6. Configuration: Relevant environment variables (hide secrets!)

Where to get help

• Documentation Issues: docs.cloudillo.org GitHub
• Server Issues: cloudillo-rs GitHub
• Community Support: community.cloudillo.org
• Development Questions: GitHub Discussions

Reporting bugs

When reporting bugs, include:

1. Clear title describing the issue
2. Expected behavior vs actual behavior
3. Reproduction steps (detailed)
4. Environment details (OS, version, installation method)
5. Logs (relevant portions, not entire logs)
6. Screenshots if applicable

Use this template:

**Environment:**
- Cloudillo version: Rust v0.1.0-alpha
- Installation: Docker / Built from source
- OS: Ubuntu 22.04
- Browser: Chrome 120

**Expected behavior:**
I expected [describe what should happen]

**Actual behavior:**
Instead, [describe what actually happens]

**Steps to reproduce:**
1. [First step]
2. [Second step]
3. [Etc.]

**Logs:**

[paste relevant log snippets]

**Screenshots:**
[if applicable]

Common Error Codes

Cloudillo uses structured error codes in format E-MODULE-TYPE:

See API Error Handling for complete error code reference.

Known Limitations (Current Version)

Refer to Status Page for up-to-date limitations.

As of v0.1.0-alpha:

• Only 20% of API handlers updated to new format
• Settings API not implemented
• References API not implemented
• Some action operations not working (reactions, stats, etc.)
• File management incomplete (update, delete, tags)
• RTDB/CRDT backend ready but client integration pending

These are expected limitations during Phase 1 development. Check Development Status for timeline on fixes.

Emergency Recovery

Complete data loss (last resort)

If your installation is completely broken:

1. Backup data directory:

cp -r /var/vol/cloudillo /backup/cloudillo-$(date +%Y%m%d)

2. Fresh install:

# Stop and remove old container
docker stop cloudillo
docker rm cloudillo

# Remove data (only if you have backup!)
# rm -rf /var/vol/cloudillo

# Start fresh
docker run -d --name cloudillo \
  -v /var/vol/cloudillo:/data \
  -p 443:443 -p 80:80 \
  -e BASE_ID_TAG=yourdomain.com \
  -e BASE_APP_DOMAIN=yourdomain.com \
  -e BASE_PASSWORD=NewPassword \
  -e ACME_EMAIL=you@example.com \
  -e ACME_TERMS_AGREED=true \
  cloudillo/cloudillo-rs:latest

3. Restore data (if possible):
   • Identity and cryptographic keys are in /data/priv/
   • User files are in /data/pub/
   • Databases are SQLite and redb files in /data/priv/

Prevention Best Practices

1. Regular backups:

# Daily backup script
#!/bin/bash
tar -czf /backup/cloudillo-$(date +%Y%m%d).tar.gz /var/vol/cloudillo
# Keep last 7 days
find /backup -name "cloudillo-*.tar.gz" -mtime +7 -delete

2. Monitor logs for warnings

3. Keep Cloudillo updated:

# For Docker
docker pull cloudillo/cloudillo-rs:latest
docker stop cloudillo
docker rm cloudillo
# Then re-run docker run command

# For built version
cd cloudillo-rs
git pull
cargo build --release
sudo systemctl restart cloudillo

4. Test in staging before upgrading production

5. Subscribe to updates:

   • Watch cloudillo-rs repository
   • Join community channels
   • Check Status Page weekly

Still Stuck?

If you’ve tried everything and are still having issues:

1. Search existing issues
2. Check GitHub Discussions
3. Ask in community forums
4. Create a new issue with full details

We’re here to help! Cloudillo is in active development, and your feedback helps make it better.