Skip to content

QUICKSTART.md

Latest commit

 

History

History
244 lines (166 loc) · 3.63 KB

QUICKSTART.md

File metadata and controls

244 lines (166 loc) · 3.63 KB

Chronos Quick Start Guide

Get Chronos up and running in minutes!

English | 简体中文

🚀 Option 1: Docker Deployment (Recommended)

The easiest way to run Chronos - perfect for production!

Prerequisites

  • Docker Desktop installed
  • At least 2GB free RAM
  • At least 5GB free disk space

One-Command Deployment

# Clone repository
git clone https://github.com/yourusername/chronos.git
cd chronos

# Copy environment file
cp .env.example .env

# Deploy with Docker Compose
docker-compose up -d --build

Access Application

Using Deployment Script

# Linux/Mac
./docker-deploy.sh start

# Windows PowerShell
.\docker-deploy.ps1 start

Manage Services

# View status
docker-compose ps

# View logs
docker-compose logs -f

# Stop services
docker-compose down

# Restart services
docker-compose restart

💻 Option 2: Local Development

For development and debugging.

Prerequisites

  • Node.js v18+ and npm
  • Python 3.12+
  • uv (Python package manager)
  • MySQL 8.0+ (or SQLite)

Backend Setup

cd Chronos-backend

# Install uv
pip install uv

# Install dependencies
uv sync

# Configure database
cp config/.secrets.toml.example config/.secrets.toml
# Edit config/.secrets.toml

# (Optional) Seed database
uv run python -m src.scripts.seed

# Start backend
uv run uvicorn src.main:app --reload

Backend runs at http://localhost:8000

Frontend Setup

cd Chronos-frontend

# Install dependencies
npm install

# Start development server
npm start

Frontend runs at http://localhost:4200

🔧 Configuration

Database Options

MySQL (Default)

# In config/settings.toml
DB_TYPE = "mysql"

SQLite (Quick Start)

# In config/settings.toml
DB_TYPE = "sqlite"
DB_NAME = "chronos.db"

Environment Variables

Edit .env file for Docker:

# Database
MYSQL_ROOT_PASSWORD=your_secure_password
MYSQL_DATABASE=chronos
MYSQL_USER=chronos
MYSQL_PASSWORD=your_secure_password

# Ports
FRONTEND_PORT=80
BACKEND_PORT=8000
MYSQL_PORT=3306

✅ Verify Installation

Check Services

# Docker
docker-compose ps

# Or use deployment script
./docker-deploy.sh status

Test API

# Health check
curl http://localhost:8000/health

# API documentation
open http://localhost:8000/docs

Test Frontend

Open browser and navigate to:

🐛 Troubleshooting

Port Already in Use

# Change ports in .env
FRONTEND_PORT=8080
BACKEND_PORT=8001
MYSQL_PORT=3307

Database Connection Failed

# Check if MySQL is running
docker-compose ps database

# Restart database
docker-compose restart database

Frontend Shows Blank Page

# Check backend connection
curl http://localhost:8000

# Clear browser cache
# Or use incognito mode

Docker Build Fails

# Clean build cache
docker-compose down
docker builder prune

# Rebuild
docker-compose up -d --build

📚 Next Steps

🆘 Need Help?

Ready to start building with Chronos! 🎉