cisco-conf-generator/docs/GETTING_STARTED.md

# 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

```bash
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

```bash
cd frontend

# Install dependencies
npm install

# Start development server
npm run dev
```

Frontend runs on: **http://localhost:3000**

### 3. Test the Setup

```bash
# 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

```bash
# From project root
chmod +x startup.sh
./startup.sh
```

This will:
1. Build frontend
2. Build backend
3. Start all services (frontend, API, database)
4. Wait for services to be ready
5. Print URLs

### Manual Docker Commands

```bash
# 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

```bash
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)

```bash
cd frontend

# Run with Vitest (future setup)
npm run test
```

## Database Access

### Using psql CLI

```bash
# 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

```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)

```bash
# 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)

```bash
# 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:
```bash
# 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

1. **Create a project** via API or GUI
2. **Add devices** (Cisco switches/routers)
3. **Build a configuration** using the GUI
4. **Validate** the configuration (check for errors)
5. **Preview** the generated CLI
6. **Test in lab** with dry-run mode
7. **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)
```yaml
# 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](ARCHITECTURE.md)
- **Security**: [docs/SECURITY.md](SECURITY.md)
- **Examples**: [docs/templates/EXAMPLE_CONFIGS.md](templates/EXAMPLE_CONFIGS.md)
- **README**: [README.md](../README.md)

---

**Happy configuring! 🔥**