223 lines
5.2 KiB
Markdown
223 lines
5.2 KiB
Markdown
# Installation Guide
|
|
|
|
This guide will walk you through installing and setting up the STUPA PDF API system on your local machine or server.
|
|
|
|
## Prerequisites
|
|
|
|
### System Requirements
|
|
- **Operating System**: Linux, macOS, or Windows (with WSL2)
|
|
- **Memory**: Minimum 4GB RAM (8GB recommended)
|
|
- **Storage**: At least 2GB free disk space
|
|
- **Network**: Internet connection for downloading dependencies
|
|
|
|
### Required Software
|
|
- **Docker**: Version 20.10 or higher
|
|
- **Docker Compose**: Version 2.0 or higher
|
|
- **Git**: For cloning the repository
|
|
- **Text Editor**: For editing configuration files
|
|
|
|
### Optional Software
|
|
- **Make**: For using the Makefile commands
|
|
- **Node.js**: Only if developing the frontend locally
|
|
- **Python 3.11**: Only if developing the backend locally
|
|
|
|
## Installation Steps
|
|
|
|
### 1. Clone the Repository
|
|
|
|
```bash
|
|
git clone https://github.com/your-org/stupa-pdf-api.git
|
|
cd stupa-pdf-api
|
|
```
|
|
|
|
### 2. Create Environment Configuration
|
|
|
|
Use the provided script to create your `.env` file:
|
|
|
|
```bash
|
|
./scripts/create-env.sh
|
|
```
|
|
|
|
This script will:
|
|
- Ask for configuration values (with sensible defaults)
|
|
- Generate secure passwords automatically
|
|
- Create a `.env` file with all required variables
|
|
|
|
Alternatively, create `.env` manually:
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
# Edit .env with your preferred editor
|
|
```
|
|
|
|
### 3. Build and Start Services
|
|
|
|
```bash
|
|
# Build all services
|
|
docker compose build
|
|
|
|
# Start all services in detached mode
|
|
docker compose up -d
|
|
```
|
|
|
|
This will start:
|
|
- MySQL database (port 3306)
|
|
- Backend API (port 8000)
|
|
- Frontend application (port 3000)
|
|
- Adminer database UI (port 8080)
|
|
|
|
### 4. Initialize Database
|
|
|
|
The database will be automatically initialized when the MySQL container starts. To run migrations manually:
|
|
|
|
```bash
|
|
# Execute migrations
|
|
docker compose exec -T db mysql -u root -p${MYSQL_ROOT_PASSWORD} ${MYSQL_DB} < backend/src/migrations/add_comparison_offers_tables.sql
|
|
docker compose exec -T db mysql -u root -p${MYSQL_ROOT_PASSWORD} ${MYSQL_DB} < backend/src/migrations/add_attachments_tables.sql
|
|
docker compose exec -T db mysql -u root -p${MYSQL_ROOT_PASSWORD} ${MYSQL_DB} < backend/src/migrations/add_url_to_comparison_offers.sql
|
|
docker compose exec -T db mysql -u root -p${MYSQL_ROOT_PASSWORD} ${MYSQL_DB} < backend/src/migrations/add_is_preferred_to_comparison_offers.sql
|
|
```
|
|
|
|
### 5. Verify Installation
|
|
|
|
Check that all services are running:
|
|
|
|
```bash
|
|
docker compose ps
|
|
```
|
|
|
|
All services should show as "Up" and "Healthy".
|
|
|
|
Test the installation:
|
|
|
|
```bash
|
|
# Test API endpoint
|
|
curl http://localhost:8000/
|
|
|
|
# Test frontend
|
|
curl http://localhost:3000/
|
|
|
|
# You should see responses from both services
|
|
```
|
|
|
|
## Post-Installation
|
|
|
|
### Access Points
|
|
|
|
After successful installation, you can access:
|
|
|
|
- **Frontend Application**: http://localhost:3000
|
|
- **API Documentation**: http://localhost:8000/docs
|
|
- **Alternative API Docs**: http://localhost:8000/redoc
|
|
- **Database UI (Adminer)**: http://localhost:8080
|
|
- Server: `db`
|
|
- Username: `root` or your configured `MYSQL_USER`
|
|
- Password: Your configured password
|
|
- Database: Your configured `MYSQL_DB`
|
|
|
|
### Initial Setup
|
|
|
|
1. **Test PDF Upload**:
|
|
- Navigate to http://localhost:3000
|
|
- Upload a test PDF form
|
|
- Verify it's processed correctly
|
|
|
|
2. **Create Test Application**:
|
|
- Use the frontend to create a new application
|
|
- Note the generated application ID and key
|
|
|
|
3. **Verify Database**:
|
|
- Access Adminer at http://localhost:8080
|
|
- Check that tables are created
|
|
- Verify test data is stored
|
|
|
|
## Troubleshooting Installation
|
|
|
|
### Common Issues
|
|
|
|
#### Docker Compose Not Found
|
|
```bash
|
|
# Install Docker Compose V2
|
|
docker compose version
|
|
# If not found, update Docker Desktop or install manually
|
|
```
|
|
|
|
#### Port Already in Use
|
|
```bash
|
|
# Find process using port (example for port 3000)
|
|
lsof -i :3000 # macOS/Linux
|
|
netstat -ano | findstr :3000 # Windows
|
|
|
|
# Change port in docker-compose.yml or stop conflicting service
|
|
```
|
|
|
|
#### Permission Denied
|
|
```bash
|
|
# Add user to docker group (Linux)
|
|
sudo usermod -aG docker $USER
|
|
# Log out and back in for changes to take effect
|
|
```
|
|
|
|
#### Database Connection Failed
|
|
```bash
|
|
# Check MySQL container logs
|
|
docker compose logs db
|
|
|
|
# Verify environment variables
|
|
docker compose config
|
|
|
|
# Ensure database is healthy
|
|
docker compose ps db
|
|
```
|
|
|
|
### Resetting Installation
|
|
|
|
To completely reset the installation:
|
|
|
|
```bash
|
|
# Stop all services
|
|
docker compose down
|
|
|
|
# Remove volumes (WARNING: Deletes all data)
|
|
docker compose down -v
|
|
|
|
# Remove all images
|
|
docker compose down --rmi all
|
|
|
|
# Start fresh
|
|
docker compose up -d
|
|
```
|
|
|
|
## Development Installation
|
|
|
|
For local development without Docker:
|
|
|
|
### Backend Development
|
|
```bash
|
|
cd backend
|
|
python -m venv venv
|
|
source venv/bin/activate # Linux/macOS
|
|
# or
|
|
venv\Scripts\activate # Windows
|
|
|
|
pip install -r requirements.txt
|
|
# Set environment variables
|
|
export MYSQL_HOST=localhost
|
|
# ... other variables
|
|
uvicorn src.service_api:app --reload
|
|
```
|
|
|
|
### Frontend Development
|
|
```bash
|
|
cd frontend
|
|
npm install
|
|
npm run dev
|
|
```
|
|
|
|
See [Development Guide](./DEVELOPMENT.md) for more details.
|
|
|
|
## Next Steps
|
|
|
|
- Review the [Configuration Guide](./CONFIGURATION.md) for advanced settings
|
|
- Check the [Quick Start Guide](./QUICK_START.md) to begin using the system
|
|
- Read the [API Reference](./API_REFERENCE.md) for integration options |