chookchat/server/README.md

# Chookpen Server

Key features:
- Real-time messaging with WebSocket support
- User authentication and account management
- Persistent message history
- Simple HTTP API for basic operations
- Built-in static file serving for web clients
- Support for encryption keys
- Active user tracking and presence notifications

## Requirements

- Java 17 or later
- Caddy (for HTTPS reverse proxy) - [Download from caddyserver.com](https://caddyserver.com/download)
- Some kind of OS, any should do
- 50mb free space, 30mb avaliable ram (yes I know, very bloated and inefficient)

## Running the Server

Prebuilt binaries are available for immediate use. Simply download the latest server release and run:

```bash
./run
```

The server will start on port 7070 by default.

## Building from Source

First, install Gradle. Unless you want to painfully compile everything manually, Gradle is your best friend.

Clone the repository and CD into the server directory. Then run:

```bash
gradle build
```

To create a distribution (you don't need to run gradle build, it will do that for you):
```bash
./gradlew installDist
```

To run the server, create the files `chatHistory` and `userDatabase` in the directory you're running it from, then run the script to start Chookpen.

## API Documentation

### HTTP Endpoints

#### Send Message
- Endpoint: `/api/send/{content}`
- Content Format: `username:{name}token:{token}message:{message}`
- Response: "Success" or error message

#### Create Account
- Endpoint: `/api/createaccount/{content}`
- Content Format: `username:{name}token:{password}`
- Response: "Success" or error message

#### Sync Messages
- Endpoint: `/api/syncmessages/{content}`
- Content Format: `username:{name}token:{token}`
- Response: Chat history or error message

#### Auth Key (being worked on for E2EE)
- Endpoint: `/api/authkey/{content}`
- Content Format: `username:{name}token:{token}authkey:{key}`
- Response: "Success" or error message

## WebSocket Interface

Connect to `/api/websocket` for real-time updates.

### WebSocket Messages

1. Server to Client:
- Ping messages: "ping"
- User updates: "!users:{user1,user2,user3}"
- Chat messages: "username: message"

2. Client to Server:
- Pong response: "pong"
- Message format: Same as HTTP send endpoint

## Setting up HTTPS with Caddy

Caddy provides automatic HTTPS and serves as a reverse proxy for your Chookpen server. [Download from caddyserver.com](https://caddyserver.com/download) or from your Linux/BSD/Illumos/Haiku/TempleOS/whatever distribution's package manager.

1. Create a `Caddyfile` in your server directory:
```
chat.yourdomain.com {
    reverse_proxy localhost:7070
}
```

2. Start Caddy:
```bash
caddy run
```

Caddy will automatically obtain and manage SSL certificates for your domain.

## Client Deployment

Place your client files in the `src/main/resources/public` directory. The server will automatically serve these static files, making the client accessible at your server's root URL.

## Maintenance

### Database Files
- `userDatabase`: Contains user credentials in format `username:token:salt`
- `chatHistory`: Stores message history
- Regular backups recommended

### Health Checks
- Server automatically maintains WebSocket connections
- Dead sessions are cleaned up automatically
- Active user count is logged

### Security Recommendations
- Keep database files secure
- Regular system updates
- Monitor for unusual login patterns
- Back up regularly:
```bash
#!/bin/bash
backup_dir="/path/to/backups"
date_stamp=$(date +%Y%m%d)
cp userDatabase "${backup_dir}/userDatabase_${date_stamp}"
cp chatHistory "${backup_dir}/chatHistory_${date_stamp}"
```