Server Guide

Getting Started

The server component of PocketLittle Toy is responsible for processing voice commands and generating responses using AI models. We provide both Docker deployment and manual deployment options.

System Requirements

• CPU: 2 cores or above
• Memory: 4GB minimum, 8GB recommended
• Storage: 20GB minimum
• Operating System: Ubuntu 20.04 or newer
• Docker version 20.10 or newer

Prerequisites

1. Docker and Docker Compose installed
2. Valid API keys for AI models (OpenAI, DeepSeek, etc.)
3. Domain name (optional, for HTTPS)
4. Basic knowledge of Linux and Docker

Deployment Files

Directory Structure

server/
├── docker-compose.yml
├── .env
├── config/
│   ├── nginx/
│   │   └── nginx.conf
│   └── app/
│       └── config.yaml
├── data/
│   └── db/
└── logs/

Configuration Files

1. .env: Environment variables

   OPENAI_API_KEY=your_api_key
   DEEPSEEK_API_KEY=your_api_key
   PORT=3000
   

2. config.yaml: Application configuration

   server:
     port: 3000
     host: 0.0.0.0
   
   ai:
     default_model: gpt-3.5-turbo
     timeout: 30000
     max_tokens: 2000
   
   audio:
     sample_rate: 16000
     channels: 1
     format: wav
   

Deployment Methods

Docker Deployment (Recommended)

1. Clone the repository:

   git clone https://github.com/your-repo/pkl-server.git
   cd pkl-server
   

2. Configure environment variables:

   cp .env.example .env
   # Edit .env with your settings
   

3. Start the services:

   docker-compose up -d
   

Manual Deployment

1. Install dependencies:

   npm install
   # or
   yarn install
   

2. Configure the application:

   cp config.example.yaml config.yaml
   # Edit config.yaml
   

3. Start the server:

   npm run start
   # or
   yarn start
   

Common Issues

Connection Issues

1. Check if the server is running:

   docker-compose ps
   # or
   pm2 status
   

2. Verify network connectivity:

   curl http://localhost:3000/health
   

API Issues

1. Validate API keys in .env
2. Check API quotas and limits
3. Review server logs:

   docker-compose logs -f app
   

Performance Issues

1. Monitor system resources:

   docker stats
   # or
   htop
   

2. Check log files for errors:

   tail -f logs/error.log
   

Maintenance

Backup

1. Database backup:

   docker-compose exec db pg_dump -U postgres > backup.sql
   

2. Configuration backup:

   tar -czf config-backup.tar.gz config/
   

Updates

1. Pull latest changes:

   git pull origin main
   

2. Update containers:

   docker-compose pull
   docker-compose up -d
   

Monitoring

1. Set up health checks
2. Configure log rotation
3. Monitor system metrics
4. Set up alerts for critical issues

Security

1. Keep system updated
2. Use HTTPS
3. Configure firewall
4. Regular security audits

API Documentation

Authentication

POST /api/auth
Content-Type: application/json

{
  "device_id": "your_device_id",
  "api_key": "your_api_key"
}

Voice Processing

POST /api/voice
Content-Type: multipart/form-data

audio_file: <binary>

Chat Completion

POST /api/chat
Content-Type: application/json

{
  "message": "Hello",
  "model": "gpt-3.5-turbo"
}

For more detailed API documentation, please visit our API Reference.