6.8 KiB
6.8 KiB
Getting Started
Prerequisites
- Docker & Docker Compose (for containerized setup)
- Python 3.11+ (for local backend development)
- Node.js 20+ (for local frontend development)
- PostgreSQL client (optional, for manual database access)
Local Development (No Docker)
1. Backend Setup
cd backend
# Create virtual environment
python3 -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
# Create .env file
cp .env.example .env
# Create database (using Docker)
docker run -d \
--name cisco-postgres \
-e POSTGRES_USER=cisco_user \
-e POSTGRES_PASSWORD=cisco_pass \
-e POSTGRES_DB=cisco_builder \
-p 5432:5432 \
postgres:16-alpine
# Wait for DB to be ready
sleep 5
# Run migrations (when using Alembic - future)
# alembic upgrade head
# Start backend server
python run.py
Backend runs on: http://localhost:8000 API docs available at: http://localhost:8000/api/v1/docs
2. Frontend Setup
cd frontend
# Install dependencies
npm install
# Start development server
npm run dev
Frontend runs on: http://localhost:3000
3. Test the Setup
# Create a test user
curl -X POST http://localhost:8000/api/v1/auth/register \
-H "Content-Type: application/json" \
-d '{
"email": "test@example.com",
"username": "testuser",
"password": "TestPass123",
"full_name": "Test User"
}'
# Login
curl -X POST http://localhost:8000/api/v1/auth/login \
-H "Content-Type: application/json" \
-d '{
"email": "test@example.com",
"password": "TestPass123"
}'
# Response includes access_token - use in Authorization header
Docker Compose (Recommended)
Quick Start
# From project root
chmod +x startup.sh
./startup.sh
This will:
- Build frontend
- Build backend
- Start all services (frontend, API, database)
- Wait for services to be ready
- Print URLs
Manual Docker Commands
# Build images
docker-compose -f docker/docker-compose.yml build
# Start services
docker-compose -f docker/docker-compose.yml up -d
# View logs
docker-compose -f docker/docker-compose.yml logs -f api
# Stop services
docker-compose -f docker/docker-compose.yml down
# Remove everything including data
docker-compose -f docker/docker-compose.yml down -v
Access Services
- Frontend: http://localhost:3000
- API: http://localhost:8000
- API Docs: http://localhost:8000/api/v1/docs
- Database: postgres://cisco_user:cisco_pass@localhost:5432/cisco_builder
Running Tests
Backend Unit Tests
cd backend
# Run all tests
pytest
# Run specific test file
pytest tests/test_cli.py
# Run with coverage
pytest --cov=app tests/
# Run specific test
pytest tests/test_cli.py::test_generate_hostname
Frontend Tests (Future)
cd frontend
# Run with Vitest (future setup)
npm run test
Database Access
Using psql CLI
# Connect to local Docker postgres
psql -h localhost -U cisco_user -d cisco_builder
# List tables
\dt
# View users
SELECT id, email, username, created_at FROM users;
# View projects
SELECT id, name, owner_id, created_at FROM projects;
# View push logs (audit trail)
SELECT id, device_id, configuration_id, status, created_at FROM push_logs;
Using Python
from sqlalchemy import create_engine, text
engine = create_engine("postgresql://cisco_user:cisco_pass@localhost:5432/cisco_builder")
with engine.connect() as conn:
result = conn.execute(text("SELECT * FROM users"))
for row in result:
print(row)
Environment Variables
Backend (.env)
# Database
DATABASE_URL="postgresql://cisco_user:cisco_pass@localhost:5432/cisco_builder"
# Security
SECRET_KEY="your-super-secret-key-min-32-chars"
ENCRYPTION_KEY="" # Leave empty for auto-generation
# Features
DEBUG=false
ENABLE_SSH_PUSH=true
REQUIRE_CONFIRMATION_BEFORE_PUSH=true
# SSH
SSH_TIMEOUT=30
NETMIKO_DEVICE_TYPE=cisco_ios
Frontend (.env)
# API endpoint
VITE_API_URL=http://localhost:8000
# App settings
VITE_APP_NAME="Cisco Config Builder"
Common Issues & Troubleshooting
Database Connection Error
Error: could not connect to server: Connection refused
Solution:
1. Check PostgreSQL is running: docker ps
2. Verify DATABASE_URL is correct
3. Wait 10s for container startup: sleep 10
Port Already in Use
Error: Address already in use
Solution:
# Find process using port
lsof -i :8000 # Backend
lsof -i :3000 # Frontend
lsof -i :5432 # Database
# Kill process
kill -9 <PID>
# Or change ports in docker-compose.yml
Frontend Can't Reach Backend
Error: CORS error or 404
Solution:
1. Check backend is running: http://localhost:8000/health
2. Check frontend proxy in vite.config.ts
3. Check VITE_API_URL in .env
SSH Connection Test
Test SSH to a Cisco device:
# Install netmiko test tool
pip install netmiko
# Test connection
python -c "
from netmiko import ConnectHandler
device = {
'device_type': 'cisco_ios',
'host': '192.168.1.10',
'username': 'admin',
'password': 'password',
'timeout': 10,
}
with ConnectHandler(**device) as net_connect:
output = net_connect.send_command('show version')
print(output)
"
Next Steps
- Create a project via API or GUI
- Add devices (Cisco switches/routers)
- Build a configuration using the GUI
- Validate the configuration (check for errors)
- Preview the generated CLI
- Test in lab with dry-run mode
- Push to production device with confirmation
Production Deployment
Pre-Flight Checklist
- Change SECRET_KEY to strong random string
- Set DEBUG=false
- Update DATABASE_URL to production PostgreSQL
- Configure HTTPS (SSL certificates)
- Set up environment-specific .env files
- Configure CORS for your domain
- Set up backup strategy
- Configure logging & monitoring
- Run security audit
- Load test the API
Example K8s Deployment (Future)
# kubernetes/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: cisco-builder-api
spec:
replicas: 3
template:
spec:
containers:
- name: api
image: cisco-builder-api:latest
env:
- name: DATABASE_URL
valueFrom:
secretKeyRef:
name: db-secret
key: url
- name: SECRET_KEY
valueFrom:
secretKeyRef:
name: app-secret
key: key
Support & Documentation
- API Docs: http://localhost:8000/api/v1/docs (Swagger UI)
- Architecture: docs/ARCHITECTURE.md
- Security: docs/SECURITY.md
- Examples: docs/templates/EXAMPLE_CONFIGS.md
- README: README.md
Happy configuring! 🔥