ilia/punimtag
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Update README.md for PostgreSQL requirement and remove SQLite references

Browse Source 
This commit updates the README.md to reflect the requirement of PostgreSQL for both development and production environments. It clarifies the database setup instructions, removes references to SQLite, and ensures consistency in the documentation regarding database configurations. Additionally, it enhances the clarity of environment variable settings and database schema compatibility between the web and desktop versions.
This commit is contained in:
Tanya
2026-01-06 11:56:08 -05:00
parent b104dcba71
commit 1f3f35d535
5 changed files with 95 additions and 540 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+24 -56
View File
@@ -33,7 +33,7 @@ A fast, simple, and modern web application for organizing and tagging photos usi
- **Python 3.12 or higher** (with pip)
- **Node.js 18+ and npm**
- **PostgreSQL** (for production, optional for development with SQLite)
- **PostgreSQL** (required for both development and production)
- **Redis** (for background job processing)
**Note:** The automated installation script (`./install.sh`) will install PostgreSQL and Redis automatically on Ubuntu/Debian systems.
@@ -98,12 +98,11 @@ cd ..
### Database Setup
**Database Configuration:**
The application uses **two separate databases**:
The application uses **two separate PostgreSQL databases**:
1. **Main database** (`punimtag`) - Stores photos, faces, people, tags, and backend user accounts
- **Default: SQLite** at `data/punimtag.db` (for development)
- **Optional: PostgreSQL** (for production)
- **Required: PostgreSQL**
2. **Auth database** (`punimtag_auth`) - Stores frontend website user accounts and moderation data
- **Required: PostgreSQL** (always uses PostgreSQL)
- **Required: PostgreSQL**
Both database connections are configured via the `.env` file.
@@ -157,10 +156,10 @@ Alternatively, use the automated script (requires sudo password):
**Configuration:**
The `.env` file in the project root contains database connection strings:
```bash
# Main application database (SQLite - default for development)
DATABASE_URL=sqlite:///data/punimtag.db
# Main application database (PostgreSQL - required)
DATABASE_URL=postgresql+psycopg2://punimtag:punimtag_password@localhost:5432/punimtag
# Auth database (PostgreSQL - always required for frontend website users)
# Auth database (PostgreSQL - required for frontend website users)
DATABASE_URL_AUTH=postgresql+psycopg2://punimtag:punimtag_password@localhost:5432/punimtag_auth
```
@@ -172,24 +171,6 @@ The web application will:
- Create all required tables with the correct schema on startup
- Match the desktop version schema exactly for compatibility
**Note:** The main database uses SQLite by default for easier development. For production, you can switch to PostgreSQL by updating `DATABASE_URL` in `.env`.
**SQLite (Default - Local Database):**
The main database uses SQLite by default for development. The `.env` file should contain:
```bash
# Main database (SQLite - default for development)
DATABASE_URL=sqlite:///data/punimtag.db
# Or use absolute path:
# DATABASE_URL=file:/home/ladmin/code/punimtag/data/punimtag.db
```
**PostgreSQL (Optional - for Production):**
To use PostgreSQL for the main database instead, set:
```bash
DATABASE_URL=postgresql+psycopg2://punimtag:punimtag_password@localhost:5432/punimtag
```
**Database Schema:**
The web version uses the **exact same schema** as the desktop version for full compatibility:
- `photos` - Photo metadata (path, filename, date_taken, processed, media_type)
@@ -469,7 +450,7 @@ punimtag/
- ✅ Job management endpoints (RQ/Redis integration)
- ✅ SQLAlchemy models for all entities
- ✅ Alembic migrations configured and applied
- ✅ Database initialized (SQLite default, PostgreSQL supported)
- ✅ Database initialized (PostgreSQL required)
- ✅ RQ worker auto-start (starts automatically with API server)
- ✅ Pending linkage moderation API for user tag suggestions
@@ -486,8 +467,7 @@ punimtag/
- ✅ All tables created automatically on startup: `photos`, `faces`, `people`, `person_encodings`, `tags`, `phototaglinkage`
- ✅ Schema matches desktop version exactly for full compatibility
- ✅ Indices configured for performance
- ✅ SQLite database at `data/punimtag.db` (auto-created if missing, default for development)
- ✅ PostgreSQL support for production deployments
- ✅ PostgreSQL database (required for both development and production)
- ✅ Separate auth database (PostgreSQL) for frontend user accounts
### Image Ingestion & Processing
@@ -578,34 +558,26 @@ punimtag/
### Database
**SQLite (Default - Local Database):**
The main database uses SQLite by default for development, configured via the `.env` file:
**PostgreSQL (Required):**
Both databases use PostgreSQL. Configure via the `.env` file:
```bash
# Main application database (SQLite - default)
DATABASE_URL=sqlite:///data/punimtag.db
# Main application database (PostgreSQL - required)
DATABASE_URL=postgresql+psycopg2://punimtag:punimtag_password@localhost:5432/punimtag
# Auth database (PostgreSQL - always required for frontend website users)
# Auth database (PostgreSQL - required for frontend website users)
DATABASE_URL_AUTH=postgresql+psycopg2://punimtag:punimtag_password@localhost:5432/punimtag_auth
```
**PostgreSQL (Optional - for Production):**
To use PostgreSQL for the main database instead:
```bash
DATABASE_URL=postgresql+psycopg2://punimtag:punimtag_password@localhost:5432/punimtag
```
**Note:** The auth database (`DATABASE_URL_AUTH`) always uses PostgreSQL and is required for frontend website user authentication features.
### Environment Variables
Configuration is managed via the `.env` file in the project root. A `.env.example` template is provided.
**Required Configuration:**
```bash
# Database (SQLite by default for development)
DATABASE_URL=sqlite:///data/punimtag.db
# Main Database (PostgreSQL - required)
DATABASE_URL=postgresql+psycopg2://punimtag:punimtag_password@localhost:5432/punimtag
# Auth Database (PostgreSQL - always required for frontend website user accounts)
# Auth Database (PostgreSQL - required for frontend website user accounts)
DATABASE_URL_AUTH=postgresql+psycopg2://punimtag:punimtag_password@localhost:5432/punimtag_auth
# JWT Secrets (change in production!)
@@ -629,15 +601,14 @@ VITE_API_URL=http://127.0.0.1:8000
**Viewer Frontend Configuration:**
Create a `.env` file in the `viewer-frontend/` directory:
```bash
# Main database connection (SQLite - matches backend default)
# Use absolute path for SQLite
DATABASE_URL=file:/home/ladmin/code/punimtag/data/punimtag.db
# Main database connection (PostgreSQL - required)
DATABASE_URL=postgresql://punimtag:punimtag_password@localhost:5432/punimtag
# Auth database connection (PostgreSQL - always required)
# Auth database connection (PostgreSQL - required)
DATABASE_URL_AUTH=postgresql://punimtag:punimtag_password@localhost:5432/punimtag_auth
# Write-capable database connection (optional, falls back to DATABASE_URL if not set)
DATABASE_URL_WRITE=file:/home/ladmin/code/punimtag/data/punimtag.db
DATABASE_URL_WRITE=postgresql://punimtag:punimtag_password@localhost:5432/punimtag
# NextAuth configuration
NEXTAUTH_URL=http://localhost:3001
@@ -651,10 +622,7 @@ cd viewer-frontend
npx prisma generate
```
**Important:** The viewer frontend uses **SQLite** for the main database (matching the backend default). The Prisma schema is configured for SQLite. If you change the backend to PostgreSQL, you'll need to:
1. Update `viewer-frontend/prisma/schema.prisma` to use `provider = "postgresql"`
2. Update `DATABASE_URL` in `viewer-frontend/.env` to the PostgreSQL connection string
3. Run `npx prisma generate` again
**Important:** The viewer frontend uses **PostgreSQL** for the main database (matching the backend). The Prisma schema is configured for PostgreSQL.
**Note:** The viewer frontend uses the same database as the backend by default. For production deployments, you may want to create separate read-only and write users for better security.
@@ -677,7 +645,7 @@ npx prisma generate
**Backend:**
- **Framework**: FastAPI (Python 3.12+)
- **Database**: PostgreSQL (default, network), SQLite (optional, local)
- **Database**: PostgreSQL (required)
- **ORM**: SQLAlchemy 2.0
- **Configuration**: Environment variables via `.env` file (python-dotenv)
- **Jobs**: Redis + RQ
@@ -743,7 +711,7 @@ npx prisma generate
## 🐛 Known Limitations
- Multi-user support with role-based permissions (single-user mode deprecated)
- SQLite for development (PostgreSQL recommended for production)
- PostgreSQL for both development and production
- GPU acceleration not yet implemented (CPU-only for now)
- Large databases (>50K photos) may require optimization
- DeepFace model downloads on first use (can take 5-10 minutes, ~100MB)