Posodobi navodila za Gitea predlogo, povezavo z bazo in web-console

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

README.md

@@ -19,6 +19,7 @@ Predloga za razvojno okolje Ruby on Rails v Dockerju. Vsebuje samo infrastruktur
 | `Dockerfile` | slika za razvoj: Ruby, sistemske knjižnice (`build-essential`, `git`, `libpq-dev`, `libyaml-dev`, `pkg-config`, `postgresql-client-18`), repozitorij PGDG, uporabnik `app` (UID 1000) |
 | `docker-compose.yml` | servis `app` (Rails na vratih 3000) in servis `db` (PostgreSQL) ter volumna `bundle` in `pgdata` |
 | `.env.example` | predloga okoljskih spremenljivk (različica PostgreSQL in dostop do baze); kopiraš jo v `.env` |
+| `.gitea/template` | seznam datotek, v katerih Gitea ob ustvarjanju repozitorija iz predloge zamenja spremenljivke z imenom repozitorija |
 | `.dockerignore` | v sliko ne kopira skrivnosti, `.git`, dnevnikov in začasnih datotek |
 | `.gitignore` | v Git ne shrani `.env`, ključev za credentials, dnevnikov ipd. |
 
@@ -35,25 +36,39 @@ Predloga za razvojno okolje Ruby on Rails v Dockerju. Vsebuje samo infrastruktur
 - **`BUNDLE_PATH` namenoma ni nastavljen.** Z njim bi `bundle install` geme nameščal v drugo mapo kot `gem install`, izvršljive datoteke (`rails`, `rake`) pa ne bi bile v `PATH`.
 - **Kontejner teče kot uporabnik `app` (UID 1000)**, zato so datoteke, ki jih ustvari (npr. `rails new`, migracije), na računalniku v lasti tvojega uporabnika. Če ima tvoj uporabnik drug UID (preveri z `id -u`), ga spremeni v `Dockerfile` in v `docker-compose.yml` (`user:`).
 - **Koda je priklopljena z `.:/app`**, zato se spremembe takoj vidijo v kontejnerju, brez ponovne gradnje slike.
-- **Podatke baze hrani volume `pgdata`**, zato ostanejo tudi po `docker compose down`.
+- **Podatke baze hrani volume `pgdata`**, zato ostanejo tudi po `docker compose down`. Priklopljen je na `/var/lib/postgresql` (ne na `/var/lib/postgresql/data`), kot zahteva slika `postgres` od različice 18 naprej. Podatki so v podmapi `<PG_MAJOR>/docker`, kar omogoča nadgradnjo s `pg_upgrade --link`.
+- **Servis `db` ima healthcheck** (`pg_isready`), servis `app` pa se zažene šele, ko je baza pripravljena na povezave.
+- **Ob zagonu servisa `app` se najprej izvede `bin/rails db:prepare`**, ki ustvari bazo (če še ne obstaja) in izvede čakajoče migracije. Po `docker compose down -v` zato baze ni treba ustvarjati ročno.
 
 ## Nov projekt iz predloge
 
-### 1. Kopiraj predlogo
+### 1. Ustvari repozitorij iz predloge
+
+Repozitorij `rails-docker-starter` je v Gitei označen kot predloga (*Make repository a template*).
+
+1. V Gitei izberi **+ → New Repository**.
+2. V polju **Template** izberi `rails-docker-starter`.
+3. Obkljukaj **Git Content**. Ostale možnosti (webhooki, oznake ...) niso potrebne.
+4. Vpiši ime novega repozitorija (npr. `moj-projekt`) in klikni **Create Repository**.
+
+Nov repozitorij dobi datoteke predloge brez njene zgodovine. Gitea v datotekah, naštetih v `.gitea/template`, zamenja spremenljivke z imenom repozitorija: v `.env.example` tako `${REPO_NAME_SNAKE}_development` postane `moj_projekt_development`.
+
+Nato repozitorij kloniraj:
 
 ```bash
-git clone <url-predloge> moj-projekt
+git clone <url-novega-repozitorija>
 cd moj-projekt
-rm -rf .git && git init
 ```
 
+Če predlogo namesto tega kloniraš neposredno (`git clone`, nato `rm -rf .git && git init`), Gitea spremenljivk ne zamenja. V `.env` moraš `${REPO_NAME_SNAKE}` zamenjati ročno, sicer Compose spremenljivko razume kot prazno in baza se imenuje `_development`.
+
 ### 2. Nastavi okoljske spremenljivke
 
 ```bash
 cp .env.example .env
 ```
 
-V `.env` vpiši ime baze, uporabnika in geslo. `APP_DATABASE_HOST` naj ostane `db` (ime servisa v Compose).
+V `.env` preveri ime baze in vpiši uporabnika in geslo. `APP_DATABASE_HOST` naj ostane `db` (ime servisa v Compose).
 
 ### 3. Zgradi sliko in namesti Rails
 
@@ -69,35 +84,53 @@ docker compose run --rm app rails new . --database=postgresql --skip-docker
 ```
 
 - `--skip-docker` prepreči, da bi Rails ustvaril svoj (produkcijski) `Dockerfile` in prepisal obstoječega.
-- Ko vpraša, ali naj prepiše `.gitignore`, odgovori `n`. Če želiš, iz Rails-ove različice ročno dodaj manjkajoče vrstice.
+- Ko vpraša, ali naj prepiše `.gitignore`, odgovori `n`. Predloga že vsebuje vse vrstice, ki jih doda Rails.
 - Ko vpraša, ali naj prepiše `README.md`, odgovori `n`, sicer izgubiš ta navodila. Navodila za aplikacijo lahko pozneje dopišeš sem.
 
 ### 5. Poveži Rails z bazo
 
-V `config/database.yml` razdelek `development` nastavi na okoljske spremenljivke:
+V `config/database.yml` dodaj nastavitve povezave v razdelek `default`, da veljajo za `development` in `test`:
 
 ```yaml
+default: &default
+  adapter: postgresql
+  encoding: unicode
+  max_connections: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
+  # Povezava na bazo v kontejnerju db (vrednosti iz .env)
+  host: <%= ENV["APP_DATABASE_HOST"] %>
+  port: <%= ENV.fetch("APP_DATABASE_PORT") { 5432 } %>
+  username: <%= ENV["APP_DATABASE_USERNAME"] %>
+  password: <%= ENV["APP_DATABASE_PASSWORD"] %>
+
 development:
   <<: *default
   database: <%= ENV["APP_DATABASE"] %>
-  host: <%= ENV["APP_DATABASE_HOST"] %>
+
-  port: <%= ENV["APP_DATABASE_PORT"] %>
+test:
-  username: <%= ENV["APP_DATABASE_USERNAME"] %>
+  <<: *default
-  password: <%= ENV["APP_DATABASE_PASSWORD"] %>
+  database: <%= ENV["APP_DATABASE"] %>_test
 ```
 
-Razdelek `test` nastavi enako, le z drugim imenom baze (npr. `<%= ENV["APP_DATABASE"] %>_test`).
+Brez teh nastavitev se Rails poskuša povezati prek lokalnega socketa in javi `PG::ConnectionBad: connection to server on socket "/var/run/postgresql/.s.PGSQL.5432" failed`.
 
-### 6. Ustvari bazo in zaženi aplikacijo
+### 6. Dovoli web-console iz omrežja Docker
+
+Brskalnik dostopa do aplikacije prek omrežja Docker (npr. `172.27.0.1`), web-console pa privzeto dovoli le `127.0.0.1`. V dnevniku se zato izpiše `Cannot render console from 172.27.0.1!`, konzola na strani z napako pa se ne prikaže. V `config/environments/development.rb` dodaj:
+
+```ruby
+  # Dovoli web-console za zahteve iz omrežij Docker (privzeti bazeni naslovov).
+  config.web_console.allowed_ips = %w[172.16.0.0/12 192.168.0.0/16]
+```
+
+### 7. Zaženi aplikacijo
 
 ```bash
-docker compose run --rm app bin/rails db:prepare
 docker compose up
 ```
 
-Aplikacija je dosegljiva na <http://localhost:3000>.
+Ob zagonu se samodejno izvede `bin/rails db:prepare`, ki ustvari bazo. Aplikacija je dosegljiva na <http://localhost:3000>.
 
-### 7. Odkomentiraj namestitev gemov v Dockerfile
+### 8. Odkomentiraj namestitev gemov v Dockerfile
 
 Ko obstajata `Gemfile` in `Gemfile.lock`, v `Dockerfile` odkomentiraj:
 
@@ -173,7 +206,13 @@ docker compose build
 ```
 
 **`could not translate host name "db"` ali `connection refused`**
-Preveri, da je v `.env` nastavljeno `APP_DATABASE_HOST=db` in da teče servis baze (`docker compose ps`). Ob prvem zagonu PostgreSQL potrebuje nekaj sekund za inicializacijo, zato ukaz po potrebi ponovi.
+Preveri, da je v `.env` nastavljeno `APP_DATABASE_HOST=db` in da teče servis baze (`docker compose ps`, stanje `healthy`). Pri `docker compose run` Compose sicer počaka na healthcheck, pri ročnem zagonu servisa `db` pa PostgreSQL ob prvem zagonu potrebuje nekaj sekund za inicializacijo.
+
+**`PG::ConnectionBad: connection to server on socket "/var/run/postgresql/.s.PGSQL.5432" failed`**
+Rails ne uporablja nastavitev iz `.env` in se poskuša povezati lokalno. Preveri `config/database.yml` (glej korak 5) in znova zaženi servis `app` (`docker compose restart app`).
+
+**Kontejner `db` se ustavi z `Error: in 18+, these Docker images are configured to store database data in a format which is compatible with "pg_ctlcluster"`**
+Volume `pgdata` je priklopljen na `/var/lib/postgresql/data`, slika `postgres` od različice 18 naprej pa pričakuje `/var/lib/postgresql`. Popravi priklop v `docker-compose.yml`. Če so v volumnu podatki starejše glavne različice, jih nadgradi s `pg_upgrade` ali izvozi in uvozi, sicer volume izbriši (`docker volume rm <projekt>_pgdata`).
 
 **`A server is already running`**
 Ostala je datoteka s PID-om strežnika: