# Configuration Guide

## API Connection Configuration

Starting from version 1.0.0-alpha, Open Notebook uses a simplified API connection system that automatically configures itself based on your deployment environment.

### How It Works

The frontend now automatically discovers the API location at runtime, eliminating the need for complex network configurations. This works for both Docker deployment modes:
- Multi-container (docker-compose with separate SurrealDB)
- Single-container (all services in one container)

### Default Configuration

By default, the API is accessible at `http://localhost:5055`. This works for most local Docker deployments where:
- You access the frontend at `http://localhost:8502`
- Your browser can directly reach `http://localhost:5055`

**No configuration needed** for standard localhost deployments!

### Custom Configuration

If you need to change the API URL (e.g., running on a different host, port, or domain), you can configure it using the `API_URL` environment variable.

#### Option 1: Using docker-compose (Recommended)

Edit your `docker.env` file:

```env
API_URL=http://your-server-ip:5055
```

Or add it to your `docker-compose.yml`:

```yaml
services:
  open_notebook:
    image: lfnovo/open_notebook:latest
    ports:
      - "8502:8502"
      - "5055:5055"  # API port must be exposed
    environment:
      - API_URL=http://your-server-ip:5055
```

#### Option 2: Using docker run

```bash
docker run -e API_URL=http://your-server-ip:5055 \
  -p 8502:8502 \
  -p 5055:5055 \
  lfnovo/open_notebook:latest
```

### Important Notes

1. **Port 5055 must be exposed**: The browser needs direct access to the API, so port 5055 must be mapped in your Docker configuration.

2. **Use the externally accessible URL**: The `API_URL` should be the URL that a browser can reach, not internal Docker networking addresses.

3. **Protocol matters**: Use `http://` for local deployments, `https://` if you've set up SSL.

### Examples

#### Running on a different host
```env
API_URL=http://192.168.1.100:5055
```

#### Running on a custom domain with SSL
```env
API_URL=https://notebook.example.com/api
```

#### Running on a custom port
```env
API_URL=http://localhost:3055
```
(Remember to update the port mapping in docker-compose accordingly)

### Troubleshooting

**"Unable to connect to server" error on login:**
1. Verify port 5055 is exposed in your Docker configuration
2. Check that `API_URL` matches the URL your browser can access
3. Try accessing `http://localhost:5055/health` directly in your browser
4. If that fails, the API isn't running or port isn't exposed

**API works but frontend doesn't connect:**
1. Check browser console for CORS errors
2. Verify `API_URL` is set correctly
3. Make sure you're using the same protocol (http/https) throughout

### Migration from Previous Versions

If you were previously exposing port 5055 manually or had custom configurations, you may need to:
1. Update your `docker.env` or environment variables to include `API_URL`
2. Ensure port 5055 is exposed in your docker-compose.yml (it's now required)
3. Remove any custom Next.js configuration or environment variables you may have added

The default configuration will work for most users without any changes.