108 lines
3.6 KiB
Markdown
108 lines
3.6 KiB
Markdown
# 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 automatically discovers the API location at runtime by analyzing the incoming HTTP request. This eliminates the need for complex network configurations and works for both Docker deployment modes:
|
|
- Multi-container (docker-compose with separate SurrealDB)
|
|
- Single-container (all services in one container)
|
|
|
|
**Auto-detection logic:**
|
|
1. If `API_URL` environment variable is set → use it (explicit override)
|
|
2. Otherwise, detect from the HTTP request:
|
|
- Uses the same hostname you're accessing the frontend from
|
|
- Automatically changes port to 5055 (API port)
|
|
- Respects `X-Forwarded-Proto` header for reverse proxy setups
|
|
3. Falls back to `http://localhost:5055` if detection fails
|
|
|
|
**Examples:**
|
|
- Access frontend at `http://localhost:8502` → API at `http://localhost:5055` ✅
|
|
- Access frontend at `http://10.20.30.20:8502` → API at `http://10.20.30.20:5055` ✅
|
|
- Access frontend at `http://my-server:8502` → API at `http://my-server:5055` ✅
|
|
|
|
**No configuration needed** for most 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:v1-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:v1-latest-single
|
|
```
|
|
|
|
### 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.
|