Add persistent PostgreSQL stack and SQLite migration

README-Docker.md

@@ -1,65 +1,62 @@
-# Queensway Europe Telco Portal - Docker (runs locally on this PC)
+# Queensway Europe Telco Portal - Docker
 
-A Docker container you run directly on your own PC, same setup as TostaSklad. Requires
-**Docker Desktop for Windows** (with WSL2 backend, the default) - download from
-https://www.docker.com/products/docker-desktop/ if you don't have it yet.
+The Docker stack contains two services:
 
-## First run
+- `telcoportal` - the Flask web application
+- `db` - PostgreSQL 16, stored in a persistent Docker volume
 
-Open a terminal (PowerShell) in this `QWE Telco` folder and run:
+## First start and SQLite import
 
-```
-docker compose up -d --build
+1. Put the existing SQLite database at `data/telco.db` next to `docker-compose.yml`.
+2. Optionally set a database password in a `.env` file:
+
+   ```env
+   TELCO_DB_PASSWORD=replace-with-a-long-random-password
+   ```
+
+3. Build and start the stack:
+
+   ```powershell
+   docker compose up -d --build
+   ```
+
+4. Open <http://localhost:8092/>.
+
+Before the web server starts, `migrate_sqlite.py` creates the PostgreSQL schema and copies all
+rows from `users`, `phones`, and `internet_connections`. IDs, password hashes, dates, comments,
+and timestamps are retained. The import runs only while PostgreSQL has no application rows; all
+later starts skip it without changing existing data.
+
+If `data/telco.db` is missing on the first start, the app exits instead of creating an empty
+production database. Check the reason with `docker compose logs telcoportal`.
+
+After a successful import, the SQLite file is no longer used by the application. Keep an
+offline backup until the migrated data has been checked.
+
+## Persistent data and backups
+
+PostgreSQL stores its files in the Docker named volume `telco-db-data`. Rebuilding or replacing
+the containers does not delete this volume. The generated Flask session key is kept separately
+in `telco-app-data`.
+
+Create a portable SQL backup:
+
+```powershell
+docker compose exec -T db pg_dump -U telco -d telco -Fc > telco-backup.dump
 ```
 
-This builds the image from `TelcoPortal-source/` (Python/Flask app) and starts the container in
-the background.
-
-Open **http://localhost:8092/** in your browser.
-
-The Mobile Phones table is pre-loaded from the one-time Excel import (see
-`TelcoPortal-source/import_excel.py` and the main README). There is no login - anyone who can
-reach the URL can view and edit.
-
-## Data persistence
-
-The `TelcoPortal-data/` folder next to this file is bind-mounted into the container so the
-database survives container restarts, rebuilds, and updates:
-
-- `TelcoPortal-data/telco.db` - the SQLite database (both Mobile Phones and Internet
-  Connectivity tables live in this one file)
-
-**Back up by simply copying `TelcoPortal-data/telco.db`.** Nothing important lives inside the
-container itself.
+`docker compose down` keeps both volumes. Do **not** use `docker compose down -v` unless you
+intend to delete the PostgreSQL database and application state.
 
 ## Common commands
 
-```
-docker compose logs -f          # follow app logs
-docker compose ps               # check container status
-docker compose down             # stop and remove the container (data folder is untouched)
-docker compose up -d            # start it again
-```
-
-## Updating after you change the source code
-
-```
+```powershell
+docker compose ps
+docker compose logs -f telcoportal
+docker compose logs -f db
+docker compose down
+docker compose up -d
 docker compose up -d --build
 ```
 
-This rebuilds the image with your latest changes from `TelcoPortal-source/` and replaces the
-running container. Your data in `TelcoPortal-data/` is not affected.
-
-## Changing the port
-
-Edit the `ports:` line in `docker-compose.yml`, e.g. `"80:8000"` to use the standard HTTP port
-instead of 8092, then run `docker compose up -d` again.
-
-## Note on this setup
-
-This was written and validated by running the Flask app directly (not inside Docker - Docker
-itself was not available where these files were generated), so the app logic, database, and
-import script are confirmed working end-to-end. The Docker build/run itself could not be
-executed from where these files were generated. Please run the "First run" command above and
-let me know if anything doesn't come up cleanly (e.g. build errors, port conflicts) so it can be
-fixed.
+To use another web port, change `"8092:8000"` in `docker-compose.yml` and recreate the stack.