Posploši CLAUDE.md za predlogo in dodaj pravila za Git

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

.dockerignore

@@ -2,6 +2,10 @@
 .git
 .gitignore
 
+# Nastavitve Bundlerja in lokalno nameščeni gemi
+.bundle
+vendor/bundle
+
 # Okoljske spremenljivke in skrivnosti
 .env
 .env.*
@@ -16,6 +20,14 @@ storage/*
 public/assets
 node_modules
 
+# Poročila testov in orodij
+coverage
+
+# Urejevalniki in sistem
+.vscode
+.idea
+.DS_Store
+
 # Docker
 Dockerfile
 docker-compose.yml

.env.example

@@ -3,7 +3,7 @@
 # Glavna različica PostgreSQL za strežnik in klient v kontejnerju app
 PG_MAJOR=18
 
-APP_DATABASE=poslovni_imenik_development
+APP_DATABASE=${REPO_NAME_SNAKE}_development
 APP_DATABASE_HOST=db
 APP_DATABASE_PORT=5432
 APP_DATABASE_USERNAME=postgres

.gitea/template

@@ -0,0 +1,3 @@
+# Datoteke, v katerih Gitea ob ustvarjanju repozitorija iz predloge
+# zamenja spremenljivke (npr. ${REPO_NAME_SNAKE}) z imenom novega repozitorija
+.env.example

.gitignore

@@ -1,21 +1,31 @@
+# Več o ignoriranju datotek: https://help.github.com/articles/ignoring-files
+
+# Nastavitve Bundlerja in lokalno nameščeni gemi
+/.bundle
+/vendor/bundle
+
 # Okoljske spremenljivke in skrivnosti
 .env
 .env.*
 !.env.example
-/config/master.key
+/config/*.key
 /config/credentials/*.key
 
-# Dnevniki in začasne datoteke
+# Dnevniki in začasne datoteke (mape ohranimo)
 /log/*
 /tmp/*
 !/log/.keep
 !/tmp/.keep
 /tmp/pids/*
+!/tmp/pids/
 !/tmp/pids/.keep
 
-# Naložene datoteke (Active Storage)
+# Naložene datoteke (Active Storage) in SQLite baze
 /storage/*
 !/storage/.keep
+/tmp/storage/*
+!/tmp/storage/
+!/tmp/storage/.keep
 
 # Prevedena sredstva
 /public/assets
@@ -23,6 +33,9 @@
 !/app/assets/builds/.keep
 /node_modules
 
+# Poročila testov in orodij
+/coverage
+
 # Urejevalniki in sistem
 .vscode/
 .idea/

CLAUDE.md

@@ -1,4 +1,4 @@
-# Poslovni imenik
+# Ime projekta
 
 ## Jezik
 
@@ -9,3 +9,11 @@
 ## Izrazoslovje
 
 - Za Docker container uporabljaj izraz **kontejner** (kontejnerja, kontejnerju ...), ne prevoda "vsebnik".
+
+## Git
+
+- Veje:
+  - `main` – stabilna veja.
+  - `dev` – razvojna veja, kamor gre tekoče delo.
+- Commiti naj bodo manjši in združeni po logičnih funkcionalnostih (en commit = ena zaokrožena sprememba).
+- Sporočila commitov so v **slovenskem jeziku**.

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:

docker-compose.yml

@@ -6,7 +6,7 @@ services:
       dockerfile: Dockerfile
       args:
         PG_MAJOR: ${PG_MAJOR:-18}
-    command: bin/rails server -b 0.0.0.0 -p 3000
+    command: bash -c "bin/rails db:prepare && bin/rails server -b 0.0.0.0 -p 3000"
     ports:
       - "3000:3000"
     env_file: .env
@@ -21,7 +21,8 @@ services:
       - .:/app
       - bundle:/usr/local/bundle
     depends_on:
-      - db
+      db:
+        condition: service_healthy
 
   db:
     image: postgres:${PG_MAJOR:-18}
@@ -30,7 +31,12 @@ services:
       POSTGRES_USER: ${APP_DATABASE_USERNAME}
       POSTGRES_PASSWORD: ${APP_DATABASE_PASSWORD}
     volumes:
-      - pgdata:/var/lib/postgresql/data
+      - pgdata:/var/lib/postgresql
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
+      interval: 2s
+      timeout: 5s
+      retries: 15
 
 volumes:
   pgdata: