---
title: Getting Started
description: Get up and running with XBP in 5 minutes
---
# Getting Started with XBP
Get your first XBP project up and running in 5 minutes.
## Step 1: Install XBP
```bash
# Standard installation
cargo install xbp
# With Kafka support
cargo install xbp --features kafka
```
Verify installation:
```bash
xbp --version
```
## Step 2: Create Configuration
Create `.xbp/xbp.json` in your project:
```json
{
"project_name": "my-app",
"port": 3000,
"build_dir": "/home/user/projects/my-app",
"app_type": "rust"
}
```
## Step 3: Run Diagnostics
Check your system health:
```bash
xbp diag
```
You should see:
- CPU, RAM, Disk metrics
- Network statistics
- Port availability
- Internet connectivity
## Step 4: Setup Your Service
### For Rust Projects
```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"
}
```
### For Next.js Projects
```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",
"npm_script": "start"
}
```
### For Python Projects
```json
{
"project_name": "python-api",
"port": 3002,
"build_dir": "/home/user/projects/python-api",
"app_type": "python",
"start_command": "python main.py"
}
```
## Step 5: Deploy Your Service
```bash
# Build the service
xbp service build my-app
# Start the service
xbp service start my-app
# Check if it's running
xbp ports -p 3000
```
## Step 6: Setup Nginx (Optional)
```bash
xbp nginx setup --domain api.example.com --port 3000
```
This creates a reverse proxy configuration for your service.
## Step 7: Add Monitoring
Update `xbp.json`:
```json
{
"project_name": "my-app",
"port": 3000,
"monitor_url": "http://localhost:3000/health",
"monitor_method": "GET",
"monitor_expected_code": 200
}
```
Test monitoring:
```bash
xbp monitor check
```
## Step 8: Setup Logging
Add log configuration:
```json
{
"log_files": [
"/var/log/app/my-app.log",
"/home/user/.pm2/logs/my-app-out.log"
]
}
```
Tail logs:
```bash
xbp tail
```
## Complete Example
Here's a complete `xbp.json` for a production application:
```json
{
"project_name": "production-app",
"port": 3000,
"build_dir": "/home/app/production-app",
"app_type": "rust",
"build_command": "cargo build --release",
"start_command": "./target/release/production-app",
"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"
}
],
"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"
],
"kafka_brokers": "localhost:9092",
"kafka_topic": "production-logs",
"environment": {
"NODE_ENV": "production",
"RUST_LOG": "info"
}
}
```
## Common Workflows
### Development Workflow
```bash
# 1. Check system
xbp diag
# 2. Start service in dev mode
xbp service dev my-app
# 3. Tail logs
xbp tail
# 4. Monitor health
xbp monitor check
```
### Deployment Workflow
```bash
# 1. Pre-deployment checks
xbp diag
xbp monitor check
# 2. Deploy
xbp service build my-app
xbp service start my-app
# 3. Verify
xbp ports -p 3000
xbp monitor check
# 4. Start monitoring
xbp monitor start &
xbp tail --ship &
```
### Troubleshooting Workflow
```bash
# 1. Check system health
xbp diag
# 2. Check ports
xbp ports
# 3. Check logs
xbp logs my-app
# 4. Check service status
xbp services
# 5. Restart if needed
xbp service stop my-app
xbp service start my-app
```
## Next Steps
### Learn More
- [Configuration Guide](/docs/configuration) - Detailed configuration options
- [CLI Reference](/docs/cli-reference) - All commands and options
- [Monitoring Guide](/docs/guides/monitoring) - Set up comprehensive monitoring
- [Deployment Guide](/docs/guides/deployment) - Production deployment strategies
### Explore Commands
- [`xbp diag`](/docs/commands/diag) - System diagnostics
- [`xbp monitor`](/docs/commands/monitor) - Health monitoring
- [`xbp tail`](/docs/commands/tail) - Log management
- [`xbp ports`](/docs/commands/ports) - Port management
- [`xbp nginx`](/docs/commands/nginx) - Nginx management
### Advanced Topics
- [Kafka Integration](/docs/guides/kafka-setup) - Centralized logging
- [Multi-Service Deployment](/docs/guides/multi-service) - Microservices
- [CI/CD Integration](/docs/guides/cicd) - Automated deployments
- [Production Best Practices](/docs/guides/production) - Production setup
## Quick Reference
### Essential Commands
```bash
xbp diag # System diagnostics
xbp monitor check # Health check
xbp tail # Tail logs
xbp ports # List ports
xbp services # List services
xbp service build <name> # Build service
xbp service start <name> # Start service
xbp nginx setup -d <domain> -p <port> # Setup Nginx
xbp redeploy <name> # Redeploy service
```
### Configuration Template
```json
{
"project_name": "PROJECT_NAME",
"port": PORT_NUMBER,
"build_dir": "/path/to/project",
"app_type": "rust|nextjs|python|nodejs",
"monitor_url": "http://localhost:PORT/health",
"log_files": ["/path/to/log.log"]
}
```
## Getting Help
### Documentation
- [Full Documentation](/docs/index)
- [CLI Reference](/docs/cli-reference)
- [Configuration Guide](/docs/configuration)
### Support
- **GitHub Issues**: [Report bugs](https://github.com/your-org/xbp/issues)
- **Email**: floris@xylex.ai
- **Community**: [Discussions](https://github.com/your-org/xbp/discussions)
### Troubleshooting
If you encounter issues:
1. Check [Troubleshooting Guide](/docs/guides/troubleshooting)
2. Run `xbp diag --debug` for detailed output
3. Check logs with `xbp tail`
4. Search [GitHub Issues](https://github.com/your-org/xbp/issues)
5. Ask in [Discussions](https://github.com/your-org/xbp/discussions)
## Tips for Success
1. **Start simple** - Begin with basic configuration
2. **Test locally** - Verify everything works before production
3. **Use diagnostics** - Run `xbp diag` regularly
4. **Monitor health** - Set up health checks early
5. **Check logs** - Use `xbp tail` for debugging
6. **Document setup** - Keep your configuration documented
7. **Automate** - Use scripts and CI/CD
## What's Next?
Now that you have XBP set up, explore these topics:
1. **[Set up monitoring](/docs/guides/monitoring)** - Keep your services healthy
2. **[Configure logging](/docs/guides/logging)** - Centralize your logs
3. **[Deploy to production](/docs/guides/deployment)** - Production-ready setup
4. **[Integrate with CI/CD](/docs/guides/cicd)** - Automate deployments
5. **[Scale your services](/docs/guides/scaling)** - Handle more traffic
Happy deploying!