Torben Sorensen
11aeac5edd
Some checks failed
Deploy to Test Environment / deploy-to-test (push) Failing after 1m10s
169 lines
4.8 KiB
Markdown
169 lines
4.8 KiB
Markdown
# Installation Guide
|
|
|
|
This guide covers setting up a local development environment for Flyer Crawler.
|
|
|
|
## Prerequisites
|
|
|
|
- Node.js 20.x or later
|
|
- Access to a PostgreSQL database (local or remote)
|
|
- Redis instance (for session management)
|
|
- Google Gemini API key
|
|
- Google Maps API key (for geocoding)
|
|
|
|
## Quick Start
|
|
|
|
If you already have PostgreSQL and Redis configured:
|
|
|
|
```bash
|
|
# Install dependencies
|
|
npm install
|
|
|
|
# Run in development mode
|
|
npm run dev
|
|
```
|
|
|
|
---
|
|
|
|
## Development Environment with Podman (Recommended for Windows)
|
|
|
|
This approach uses Podman with an Ubuntu container for a consistent development environment.
|
|
|
|
### Step 1: Install Prerequisites on Windows
|
|
|
|
1. **Install WSL 2**: Podman on Windows relies on the Windows Subsystem for Linux.
|
|
|
|
```powershell
|
|
wsl --install
|
|
```
|
|
|
|
Run this in an administrator PowerShell.
|
|
|
|
2. **Install Podman Desktop**: Download and install [Podman Desktop for Windows](https://podman-desktop.io/).
|
|
|
|
### Step 2: Set Up Podman
|
|
|
|
1. **Initialize Podman**: Launch Podman Desktop. It will automatically set up its WSL 2 machine.
|
|
2. **Start Podman**: Ensure the Podman machine is running from the Podman Desktop interface.
|
|
|
|
### Step 3: Set Up the Ubuntu Container
|
|
|
|
1. **Pull Ubuntu Image**:
|
|
|
|
```bash
|
|
podman pull ubuntu:latest
|
|
```
|
|
|
|
2. **Create a Podman Volume** (persists node_modules between container restarts):
|
|
|
|
```bash
|
|
podman volume create node_modules_cache
|
|
```
|
|
|
|
3. **Run the Ubuntu Container**:
|
|
|
|
Open a terminal in your project's root directory and run:
|
|
|
|
```bash
|
|
podman run -it -p 3001:3001 -p 5173:5173 --name flyer-dev \
|
|
-v "$(pwd):/app" \
|
|
-v "node_modules_cache:/app/node_modules" \
|
|
ubuntu:latest
|
|
```
|
|
|
|
| Flag | Purpose |
|
|
| ------------------------------------------- | ------------------------------------------------ |
|
|
| `-p 3001:3001` | Forwards the backend server port |
|
|
| `-p 5173:5173` | Forwards the Vite frontend server port |
|
|
| `--name flyer-dev` | Names the container for easy reference |
|
|
| `-v "...:/app"` | Mounts your project directory into the container |
|
|
| `-v "node_modules_cache:/app/node_modules"` | Mounts the named volume for node_modules |
|
|
|
|
### Step 4: Configure the Ubuntu Environment
|
|
|
|
You are now inside the Ubuntu container's shell.
|
|
|
|
1. **Update Package Lists**:
|
|
|
|
```bash
|
|
apt-get update
|
|
```
|
|
|
|
2. **Install Dependencies**:
|
|
|
|
```bash
|
|
apt-get install -y curl git
|
|
curl -sL https://deb.nodesource.com/setup_20.x | bash -
|
|
apt-get install -y nodejs
|
|
```
|
|
|
|
3. **Navigate to Project Directory**:
|
|
|
|
```bash
|
|
cd /app
|
|
```
|
|
|
|
4. **Install Project Dependencies**:
|
|
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
### Step 5: Run the Development Server
|
|
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
### Step 6: Access the Application
|
|
|
|
- **Frontend**: http://localhost:5173
|
|
- **Backend API**: http://localhost:3001
|
|
|
|
### Managing the Container
|
|
|
|
| Action | Command |
|
|
| --------------------- | -------------------------------- |
|
|
| Stop the container | Press `Ctrl+C`, then type `exit` |
|
|
| Restart the container | `podman start -a -i flyer-dev` |
|
|
| Remove the container | `podman rm flyer-dev` |
|
|
|
|
---
|
|
|
|
## Environment Variables
|
|
|
|
This project is configured to run in a CI/CD environment and does not use `.env` files. All configuration must be provided as environment variables.
|
|
|
|
For local development, you can export these in your shell or use your IDE's environment configuration:
|
|
|
|
| Variable | Description |
|
|
| --------------------------- | ------------------------------------- |
|
|
| `DB_HOST` | PostgreSQL server hostname |
|
|
| `DB_USER` | PostgreSQL username |
|
|
| `DB_PASSWORD` | PostgreSQL password |
|
|
| `DB_DATABASE_PROD` | Production database name |
|
|
| `JWT_SECRET` | Secret string for signing auth tokens |
|
|
| `VITE_GOOGLE_GENAI_API_KEY` | Google Gemini API key |
|
|
| `GOOGLE_MAPS_API_KEY` | Google Maps Geocoding API key |
|
|
| `REDIS_PASSWORD_PROD` | Production Redis password |
|
|
| `REDIS_PASSWORD_TEST` | Test Redis password |
|
|
|
|
---
|
|
|
|
## Seeding Development Users
|
|
|
|
To create initial test accounts (`admin@example.com` and `user@example.com`):
|
|
|
|
```bash
|
|
npm run seed
|
|
```
|
|
|
|
After running, you may need to restart your IDE's TypeScript server to pick up any generated types.
|
|
|
|
---
|
|
|
|
## Next Steps
|
|
|
|
- [Database Setup](DATABASE.md) - Set up PostgreSQL with required extensions
|
|
- [Authentication Setup](AUTHENTICATION.md) - Configure OAuth providers
|
|
- [Deployment Guide](DEPLOYMENT.md) - Deploy to production
|