npm package: @nervur-ai/homeserver
Description: CLI tool to quickly spin up a Continuwuity Matrix homeserver optimized for nervur-brain
Author: Nervur
Latest version: 0.1.5

# @nervur-ai/homeserver

CLI tool to quickly spin up a Continuwuity Matrix homeserver optimized for nervur-brain usage.

## Quick Start

```bash
npx @nervur-ai/homeserver init
```

This single command will:
- ✅ Verify Docker is installed and running
- ✅ Guide you through an interactive setup wizard
- ✅ Generate all necessary configuration files
- ✅ Pull Docker images and start your homeserver
- ✅ Verify everything is working

## Requirements

- **Docker** - [Install Docker](https://docs.docker.com/get-docker/)
- **Node.js** >= 18.0.0

## Installation Methods

### Option 1: Direct npx usage (recommended)

No installation needed! Just run:

```bash
npx @nervur-ai/homeserver init
```

### Option 2: Global installation

```bash
npm install -g @nervur-ai/homeserver
nervur-homeserver init
```

### Option 3: Local project installation

```bash
npm install @nervur-ai/homeserver
npx nervur-homeserver init
```

## Commands

### `init`

Initialize a new Continuwuity homeserver with interactive setup wizard.

```bash
npx @nervur-ai/homeserver init
```

**What it does:**
1. Runs pre-flight checks (Docker, ports, permissions)
2. Asks for your server name (domain)
3. Lets you choose between Cloudflare Tunnel or Static IP
4. Generates docker-compose.yml, config files, and documentation
5. Pulls Docker images
6. Starts the homeserver
7. Verifies it's running

### `status`

Check if your homeserver is running and healthy.

```bash
npx @nervur-ai/homeserver status
```

### `logs`

View homeserver logs.

```bash
# View last 50 lines
npx @nervur-ai/homeserver logs

# Follow logs in real-time
npx @nervur-ai/homeserver logs --follow
```

### `start`

Start a stopped homeserver.

```bash
npx @nervur-ai/homeserver start
```

### `stop`

Stop the running homeserver.

```bash
npx @nervur-ai/homeserver stop
```

### `restart`

Restart the homeserver (useful after config changes).

```bash
npx @nervur-ai/homeserver restart
```

## Setup Options

### Cloudflare Tunnel (Recommended)

- ✅ No static IP required
- ✅ Works behind NAT/firewall
- ✅ Free SSL certificate
- ✅ DDoS protection

**Steps:**
1. Run `npx @nervur-ai/homeserver init`
2. Select "Cloudflare Tunnel"
3. Get a tunnel token from [Cloudflare Zero Trust](https://one.dash.cloudflare.com/)
4. Configure the public hostname in Cloudflare dashboard

### Static IP + DNS

- Requires control over your domain's DNS
- Requires a static IP address
- Ports 8008 and 8448 must be accessible

**Steps:**
1. Run `npx @nervur-ai/homeserver init`
2. Select "Static IP + DNS"
3. Configure DNS records as instructed
4. Ensure firewall allows ports 8008 and 8448

## Creating Your First User

After setup, create an admin user:

```bash
docker exec -it continuwuity register_new_matrix_user -c /data/homeserver.yaml http://localhost:8008
```

Follow the prompts to set:
- Username
- Password
- Admin status (yes)

## Next Steps

1. **Create an admin user** (see above)
2. **Install nervur-brain** and connect it to your homeserver
3. **Start using Matrix** with your new homeserver!

## Configuration

All configuration files are generated in your current directory:

- `docker-compose.yml` - Docker service definitions
- `continuwuity-config.yaml` - Homeserver configuration
- `.env` - Environment variables
- `HOMESERVER-README.md` - Setup-specific documentation

To modify configuration:
1. Edit `continuwuity-config.yaml`
2. Run `npx @nervur-ai/homeserver restart`

## Data Storage

All homeserver data is stored in the data directory you specified during setup (default: `./nervur-homeserver-data`):

- Database (`homeserver.db`)
- Media files (`media/`)
- Log files

**Important:** Back up this directory regularly!

## Troubleshooting

### Homeserver won't start

```bash
# Check Docker is running
docker info

# View logs
npx @nervur-ai/homeserver logs

# Check status
npx @nervur-ai/homeserver status
```

### Ports already in use

If ports 8008 or 8448 are already in use, stop the conflicting service:

```bash
# Find what's using the port
lsof -i :8008
lsof -i :8448
```

### Can't connect externally

**For Cloudflare Tunnel:**
- Verify tunnel is active in Cloudflare dashboard
- Check public hostname points to `http://continuwuity:8008`

**For Static IP:**
- Verify DNS records are configured correctly
- Check firewall allows ports 8008 and 8448
- Test with: `curl http://your-ip:8008/_matrix/client/versions`

### Permission denied

If you get permission errors on the data directory:

```bash
# Option 1: Choose a different directory
npx @nervur-ai/homeserver init

# Option 2: Fix permissions
sudo chown -R $USER:$USER ./nervur-homeserver-data
```

## Nervur-Optimized Defaults

This tool configures Continuwuity with settings optimized for nervur-brain:

- **Database:** SQLite (leveldb fallback)
- **Registration:** Disabled by default (use shared secret)
- **Media uploads:** 50MB max
- **Metrics:** Disabled
- **URL previews:** Disabled
- **Federation:** Enabled with whitelist support

## Development

```bash
# Clone the repository
git clone https://github.com/nervur-ai/homeserver.git
cd homeserver

# Install dependencies
npm install

# Link for local development
npm link

# Test locally
nervur-homeserver init
```

## License

MIT License - See [LICENSE](LICENSE) file for details.

## Links

- [GitHub Repository](https://github.com/nervur-ai/homeserver)
- [nervur-brain](https://github.com/nervur-ai/nervur-brain)
- [Continuwuity](https://github.com/continuwuity/continuwuity)
- [Matrix Protocol](https://matrix.org/)

## Support

For issues and questions:
- [GitHub Issues](https://github.com/nervur-ai/homeserver/issues)
- [Matrix Community](https://matrix.to/#/#nervur:matrix.org)