---
title: Configuration
description: Complete guide to configuring XBP with xbp.json
---
# Configuration
XBP uses a `xbp.json` file for configuration. This file can be placed in:
- `.xbp/xbp.json` (recommended)
- `xbp.json` (project root)
## Basic Configuration
### Minimal Example
```json
{
"project_name": "my-app",
"port": 3000,
"build_dir": "/home/user/projects/my-app"
}
```
### Complete Example
```json
{
"project_name": "my-application",
"port": 3000,
"build_dir": "/home/user/projects/my-app",
"app_type": "rust",
"build_command": "cargo build --release",
"start_command": "./target/release/my-app",
"install_command": "cargo fetch",
"services": [
{
"name": "api",
"target": "rust",
"port": 3000,
"branch": "main",
"build_dir": "/home/user/projects/api",
"url": "https://api.example.com"
},
{
"name": "frontend",
"target": "nextjs",
"port": 3001,
"branch": "main",
"build_dir": "/home/user/projects/frontend",
"url": "https://app.example.com",
"npm_script": "start"
}
],
"monitor_url": "https://api.example.com/health",
"monitor_method": "GET",
"monitor_expected_code": 200,
"monitor_interval": 60,
"log_files": [
"/var/log/app/api.log",
"/var/log/app/frontend.log",
"/home/user/.pm2/logs/api-out.log"
],
"kafka_brokers": "localhost:9092",
"kafka_topic": "application-logs",
"kafka_public_url": "https://kafka.example.com:9092",
"environment": {
"NODE_ENV": "production",
"RUST_LOG": "info",
"DATABASE_URL": "postgresql://localhost/mydb"
}
}
```
## Configuration Fields
### Core Fields
#### `project_name` (required)
- **Type**: String
- **Description**: Name of your project
- **Example**: `"my-application"`
#### `port` (required)
- **Type**: Number (1-65535)
- **Description**: Main application port
- **Example**: `3000`
#### `build_dir` (required)
- **Type**: String
- **Description**: Absolute path to project directory
- **Example**: `"/home/user/projects/my-app"`
#### `app_type` (optional)
- **Type**: String
- **Description**: Application type for auto-detection
- **Options**: `"rust"`, `"nextjs"`, `"nodejs"`, `"python"`, `"expressjs"`
- **Example**: `"rust"`
#### `build_command` (optional)
- **Type**: String
- **Description**: Command to build the application
- **Example**: `"cargo build --release"`
#### `start_command` (optional)
- **Type**: String
- **Description**: Command to start the application
- **Example**: `"./target/release/my-app"`
#### `install_command` (optional)
- **Type**: String
- **Description**: Command to install dependencies
- **Example**: `"cargo fetch"` or `"npm install"`
### Multi-Service Configuration
#### `services` (optional)
- **Type**: Array of Service objects
- **Description**: Multiple services in one project
**Service Object Fields:**
```json
{
"name": "api", // Required: Service name
"target": "rust", // Required: Service type
"port": 3000, // Required: Service port
"branch": "main", // Required: Git branch
"build_dir": "/path", // Optional: Service directory
"url": "https://...", // Optional: Public URL
"npm_script": "start", // Optional: NPM script name
"crate_name": "my_api" // Optional: Rust crate name
}
```
**Example:**
```json
{
"services": [
{
"name": "api",
"target": "rust",
"port": 3000,
"branch": "main",
"url": "https://api.example.com"
},
{
"name": "frontend",
"target": "nextjs",
"port": 3001,
"branch": "main",
"url": "https://app.example.com",
"npm_script": "start"
},
{
"name": "worker",
"target": "python",
"port": 3002,
"branch": "main"
}
]
}
```
### Monitoring Configuration
#### `monitor_url` (optional)
- **Type**: String (URL)
- **Description**: URL to monitor for health checks
- **Example**: `"https://api.example.com/health"`
#### `monitor_method` (optional)
- **Type**: String
- **Description**: HTTP method for monitoring
- **Options**: `"GET"`, `"POST"`, `"PUT"`, `"DELETE"`, `"HEAD"`
- **Default**: `"GET"`
- **Example**: `"GET"`
#### `monitor_expected_code` (optional)
- **Type**: Number (100-599)
- **Description**: Expected HTTP status code
- **Default**: `200`
- **Example**: `200`
#### `monitor_interval` (optional)
- **Type**: Number (seconds)
- **Description**: Interval between health checks
- **Default**: `60`
- **Example**: `60`
**Complete Monitoring Example:**
```json
{
"monitor_url": "https://api.example.com/health",
"monitor_method": "GET",
"monitor_expected_code": 200,
"monitor_interval": 30
}
```
### Logging Configuration
#### `log_files` (optional)
- **Type**: Array of Strings
- **Description**: Log files to tail
- **Example**:
```json
{
"log_files": [
"/var/log/app/api.log",
"/var/log/app/worker.log",
"/home/user/.pm2/logs/api-out.log",
"/home/user/.pm2/logs/api-error.log"
]
}
```
#### `kafka_brokers` (optional)
- **Type**: String
- **Description**: Kafka broker addresses
- **Format**: `"host:port"` or `"host1:port1,host2:port2"`
- **Example**: `"localhost:9092"`
#### `kafka_topic` (optional)
- **Type**: String
- **Description**: Kafka topic for logs
- **Example**: `"application-logs"`
#### `kafka_public_url` (optional)
- **Type**: String (URL)
- **Description**: Public Kafka URL
- **Example**: `"https://kafka.example.com:9092"`
**Complete Logging Example:**
```json
{
"log_files": [
"/var/log/app/api.log",
"/var/log/app/frontend.log"
],
"kafka_brokers": "kafka1.example.com:9092,kafka2.example.com:9092",
"kafka_topic": "production-logs",
"kafka_public_url": "https://kafka.example.com:9092"
}
```
### Environment Variables
#### `environment` (optional)
- **Type**: Object (key-value pairs)
- **Description**: Environment variables for services
- **Example**:
```json
{
"environment": {
"NODE_ENV": "production",
"RUST_LOG": "info",
"DATABASE_URL": "postgresql://localhost/mydb",
"API_KEY": "secret-key",
"PORT": "3000"
}
}
```
### Legacy Fields
For backward compatibility:
#### `target` (deprecated)
- Use `app_type` instead
- **Type**: String
- **Example**: `"rust"`
#### `branch` (optional)
- **Type**: String
- **Description**: Git branch name
- **Example**: `"main"`
#### `crate_name` (optional)
- **Type**: String
- **Description**: Rust crate name
- **Example**: `"my_api"`
#### `npm_script` (optional)
- **Type**: String
- **Description**: NPM script to run
- **Example**: `"start"` or `"dev"`
#### `url` (optional)
- **Type**: String (URL)
- **Description**: Public URL
- **Example**: `"https://example.com"`
## Configuration Examples
### Rust API
```json
{
"project_name": "rust-api",
"port": 3000,
"build_dir": "/home/user/projects/rust-api",
"app_type": "rust",
"build_command": "cargo build --release",
"start_command": "./target/release/rust-api",
"monitor_url": "http://localhost:3000/health",
"log_files": ["/var/log/rust-api.log"]
}
```
### Next.js Frontend
```json
{
"project_name": "nextjs-app",
"port": 3001,
"build_dir": "/home/user/projects/nextjs-app",
"app_type": "nextjs",
"build_command": "npm run build",
"start_command": "npm start",
"install_command": "npm install",
"npm_script": "start",
"monitor_url": "http://localhost:3001",
"environment": {
"NODE_ENV": "production"
}
}
```
### Python Worker
```json
{
"project_name": "python-worker",
"port": 3002,
"build_dir": "/home/user/projects/worker",
"app_type": "python",
"start_command": "python main.py",
"install_command": "pip install -r requirements.txt",
"log_files": ["/var/log/worker.log"]
}
```
### Multi-Service Microservices
```json
{
"project_name": "microservices",
"port": 3000,
"build_dir": "/home/user/projects/microservices",
"services": [
{
"name": "auth-service",
"target": "rust",
"port": 3000,
"branch": "main",
"url": "https://auth.example.com"
},
{
"name": "api-gateway",
"target": "nodejs",
"port": 3001,
"branch": "main",
"url": "https://api.example.com"
},
{
"name": "frontend",
"target": "nextjs",
"port": 3002,
"branch": "main",
"url": "https://app.example.com"
}
],
"monitor_url": "https://api.example.com/health",
"kafka_brokers": "localhost:9092",
"kafka_topic": "microservices-logs"
}
```
## Validation
XBP validates your configuration on load. Common errors:
### Missing Required Fields
```bash
Error: Missing required field 'project_name'
```
**Fix**: Add all required fields.
### Invalid Port
```bash
Error: Port must be between 1 and 65535
```
**Fix**: Use valid port number.
### Invalid URL
```bash
Error: Invalid URL format for monitor_url
```
**Fix**: Use complete URL with protocol.
## Best Practices
1. **Use `.xbp/xbp.json`** for project-specific config
2. **Version control** your `xbp.json`
3. **Use environment variables** for secrets
4. **Document custom commands** in comments
5. **Test configuration** with `xbp config`
6. **Keep services organized** with clear names
7. **Use absolute paths** for directories
## Next Steps
- [CLI Reference](/docs/cli-reference)
- [Monitoring Guide](/docs/guides/monitoring)
- [Logging Guide](/docs/guides/logging)
- [Deployment Guide](/docs/guides/deployment)