@@ -1,9 +1,18 @@
+# Copy to .env, or let ./install.sh generate it for you.
+# .env is gitignored: it holds your machine's own values.
+
 COMPOSE_PROJECT_NAME=php-devforge
 COMPOSE_FILE=docker-compose.yml:docker-compose.override.yml
 
 #### domain ####
 DEV_DOMAIN=phpforge.dev
 
+##### WHERE YOUR PROJECTS LIVE (on the host) #####
+# Mounted at /home/php-devforge/public_html inside the containers, which is where
+# Apache and PHP look. Only this side changes; the container path is fixed.
+# Symlinks must point INSIDE this folder, or the container cannot follow them.
+PROJECTS_DIR=${HOME}/php-devforge
+
 ##### USER #####
 USERNAME=${USER}
 
@@ -19,6 +28,12 @@ DNS_PORT=5354
 ##### DEFAULT PHP VERSION #####
 PHP_VERSION=84
 
+##### HOST USER #####
+# The PHP containers adopt this uid/gid, so files they create are yours and
+# node_modules can be deleted without sudo. Check yours with: id -u ; id -g
+PUID=1000
+PGID=1000
+
 ##### NODE VERSION (built into the PHP images) #####
 # Changing this needs a rebuild: docker compose build php83dev php84dev
 NODE_VERSION=24
 
@@ -3,3 +3,5 @@
 /certificates/*
 !/certificates/.gitkeep
 /.caroot
+
+/.env
@@ -32,53 +32,41 @@ The environment automatically generates URLs based on your project folder struct
 
 1. **Clone the repository:**
    ```bash
-   git clone git@github.com:zelti/php-devforge.git $HOME/php-devforge-config
-   cd $HOME/php-devforge-config
+   git clone git@github.com:zelti/php-devforge.git
+   cd php-devforge
    ```
-    It’s recommended to clone the project inside your home directory.
-    This ensures the provided bash alias will work correctly.
+    Clone it wherever you like: the scripts and aliases resolve their own location.
 
-2. **Configure environment variables:**
-   Edit the `.env` file to customize:
-   - `DEV_DOMAIN`: Your development domain (default: phpforge.dev)
-   - `PHP_VERSION`: Default PHP version (83 for 8.3, 84 for 8.4)
-   - `USERNAME`: Your system username
+2. **Run the installer:**
+   ```bash
+   ./install.sh
+   ```
+   It asks for your domain, where your projects should live and the default PHP
+   version, finds a free DNS port, detects your user id, writes `.env`, creates the
+   projects folder, and offers to generate the certificates and configure local DNS.
 
-3. **Install SSL certificates:**
+   Safe to re-run: your current `.env` supplies the defaults. For unattended use:
    ```bash
-   ./install_cert.sh
+   ./install.sh --yes --domain=mydomain.dev --projects-dir=~/code
+   ./install.sh --help        # every option
    ```
-   This script:
-   - Runs mkcert **inside a Docker container** — nothing is installed on your machine
-   - Generates wildcard SSL certificates for `*.phpforge.dev` into `certificates/`
-   - Saves the Certificate Authority (CA) in `.caroot/`, and reuses it on every later run
-   - Installs that CA in your system trust store, and in Firefox/Chrome when `certutil` is available
 
-   It will ask for your password once: adding the CA to the system trust store is the
-   only step that cannot happen inside a container, because a container has its own
-   trust store. You will not be asked again on later runs.
+   Nothing needs `sudo` except the DNS step, and only if you accept it.
 
-4. **Setup local DNS:**
+3. **Load the shortcuts (optional):**
    ```bash
-   ./setup-local-dns.sh
+   source aliases.bash
    ```
-   This configures your system to resolve `*.phpforge.dev` domains to `127.0.0.1`.
-
-5. **Source the aliases (optional but recommended):**
-    ```bash
-    source aliases.bash
-    ```
-    Or add the following to your `~/.bashrc` for permanent availability:
-    ```bash
-    source $HOME/php-devforge-config/aliases.bash
-    ```
+   Or add that line to your `~/.bashrc`, using the full path to this folder.
 
-6. **Start the containers:**
+4. **Start the containers:**
     ```bash
-    docker-compose up -d
+    docker compose up -d
     ```
     (If you sourced the aliases, you can use `forge:start` instead)
 
+    Check it works: `https://welcome--sites.phpforge.dev`
+
 ## 💻 Usage
 
 ### ▶️ Starting and Stopping
@@ -118,11 +106,25 @@ forge:logs:php84
 ### 🌐 Accessing Your Projects
 
 1. **Create project structure:**
-   Place your PHP projects in `/home/php-devforge/public_html/` 
-   it will create this folder on your local you will need to change the folder user and group manually for first time
+   Your projects live in the folder you chose during install (`PROJECTS_DIR` in
+   `.env`, `~/php-devforge` by default). The installer creates it with:
+
    ```
-    sudo chown yourUser:www-data -R /home/php-devforge
-    ```
+   ~/php-devforge/
+   ├── projects/          your actual code
+   └── sites/             one symlink per project, for shorter URLs
+       └── welcome/       a test page
+   ```
+
+   Inside the containers this is always `/home/php-devforge/public_html`, which is
+   where Apache and PHP look. Only the host side is configurable.
+
+   **Symlinks must point inside `PROJECTS_DIR`.** The containers only see that
+   folder, so a link to anywhere else resolves to nothing and returns 404.
+
+   No `chown` is needed. The PHP containers adopt your user id at startup
+   (`PUID`/`PGID` in `.env`), so files they create belong to you and `node_modules`
+   can be deleted without `sudo`.
 
 2. **URL Structure:**
    Projects are accessible via automatically generated URLs:
@@ -198,7 +200,7 @@ Plain PHP app → `plain-php--site.phpforge.dev`
 - **DNS resolution not working**: Ensure you ran `./setup-local-dns.sh` and restarted your browser or system. You may need to flush DNS cache.
 - **SSL certificate not trusted**: Make sure you ran `./install_cert.sh` and restart your browser afterwards. Check the CA is present with `openssl verify -CAfile .caroot/rootCA.pem certificates/php-devforge.pem`. Firefox keeps its own trust store on Linux, so install `nss` (Arch) or `libnss3-tools` (Debian/Ubuntu) and re-run the script if Firefox still complains.
 - **Containers not starting**: Check that Docker and Docker Compose are installed and running. Ensure ports 80 and 443 are not in use by other services.
-- **Permission issues with public_html**: Run `sudo chown yourUser:www-data -R /home/php-devforge` to set correct ownership.
+- **Permission issues with public_html**: Check that `PUID`/`PGID` in `.env` match your own ids (`id -u`, `id -g`), then recreate the containers with `docker compose up -d --force-recreate`. The containers adopt those ids on startup, so files they write are owned by you.
 - **PHP version not switching**: Use the aliases `forge:use:php83` or `forge:use:php84` to change the default version, or append `--p83`/`--p84` to the URL.
 - **Aliases not working**: Ensure you sourced `aliases.bash` or added it to your `~/.bashrc`.
 
 
@@ -216,9 +216,50 @@ approach.
 
 ## 💬 Needs discussion before implementing
 
-### 7. Interactive installer 💬 DISCUSS FIRST
+### 7. Interactive installer — DONE
+
+- [x] **Implemented as `install.sh`**
+
+      Asks for domain, projects folder and default PHP version; finds a free DNS port;
+      detects `PUID`/`PGID` with `id -u`/`id -g`; writes `.env`; creates the projects
+      folder; and offers to run the certificate and DNS steps. Re-running is safe: the
+      current `.env` supplies the defaults, and the old one is kept as `.env.backup`.
+      Flags for unattended use: `--domain=`, `--projects-dir=`, `--php=`, `--dns-port=`,
+      `--yes`, `--skip-cert`, `--skip-dns`. With no terminal it refuses to run rather
+      than silently accepting defaults.
+
+      **Config split:** `.env` is now generated and gitignored; `.env.example` is the
+      tracked template. This also fixes `forge:use:php83` dirtying the git tree on every
+      PHP version switch, and stops personal values (domain, uid, paths) being committed.
+      Anyone with an existing clone will see `.env` drop out of version control; their
+      local file is untouched.
+
+      **Projects folder:** `PROJECTS_DIR` on the host, `~/php-devforge` by default,
+      mounted at the fixed `/home/php-devforge/public_html` inside the containers — so
+      Apache, the Lua resolver and PHP need no changes. Only 2 lines in compose. The
+      installer creates `projects/` for code and `sites/` for symlinks, plus a
+      `sites/welcome` test page. No `sudo` at any point, thanks to task 8.
+
+      **Bug found while testing — hyphens in project names were broken.** The Lua split
+      the host with `[^%-%-]+`, which is "not a hyphen", not "split on `--`". So:
+
+      | Host | Resolved to | |
+      |---|---|---|
+      | `mi-app--sites` | `sites/app/mi` | wrong |
+      | `laravel-app--sites` | `sites/app/laravel` | wrong |
+      | `miapp--sites` | `sites/miapp` | fine |
+
+      **All three examples in the README** (`laravel-app`, `symfony-app`, `plain-php`)
+      were broken, and had been all along. Fixed by replacing `--` with a sentinel that
+      cannot occur in a hostname before splitting. Verified: `mi-app--sites`,
+      `laravel-app--sites`, `a--b--c` and `mi-app--sites--p83` all resolve correctly.
 
-- [ ] **Agree on the approach** (questions below), then implement
+      **README updated:** installer flow, the new folder layout, the warning that
+      symlinks must point inside `PROJECTS_DIR`, and the clone path is no longer forced
+      (aliases resolve their own location since task 3).
+
+<details>
+<summary>Original open questions (kept for the record)</summary>
 
 Goal: replace the manual README steps with `./install.sh`, which asks for the
 settings and does the setup.
@@ -267,12 +308,66 @@ container and does not need to change:
   ```
 
   The same idea applies to ports 80 and 443.
+
+</details>
 - `aliases.bash` hardcodes `$HOME/php-devforge-config`. Should the installer generate
   the aliases file with the real path, or should the aliases derive it themselves?
 
-### 8. Container user / file ownership 💬 DISCUSS FIRST
-
-- [ ] **Choose an option** (A / B / C below), then implement
+### 8. Container user / file ownership — DONE
+
+- [x] **Implemented: the container adopts the host uid at startup (PUID/PGID)**
+
+      Measured first, rather than reasoned about. The host user is uid 1000, the
+      container ran as uid 33 (`www-data`), and:
+      - a normal user-owned folder was **read-only** to the container
+      - `chgrp 33` on your own folder fails without root — which is *why* the README
+        demanded `sudo chown`, not laziness
+      - `--user 1000:1000` at runtime **killed the container**: uid 1000 had no passwd
+        entry, so `$HOME` was empty and the entrypoint failed writing `/.bashrc`
+      - `pnpm install` in a plain user folder produced nothing at all
+
+      Publishing prebuilt images was wanted (task 16), so baking the host uid at build
+      time was ruled out. Chosen instead: keep the image generic and adjust the uid when
+      the container starts.
+
+      **What changed**
+      - Dockerfile: the dev user gets **its own group** and defaults to uid/gid 1000
+        (the usual first Linux user, so most hosts need no adjustment at all). The
+        `sed` rewriting `www-data`'s home in `/etc/passwd` was dropped as vestigial.
+      - `USER php-devforge` removed. The container starts as root, which is how the
+        official `php:fpm` image works: a root master dropping workers to an
+        unprivileged user. That `USER` line was what forced the old `exec sudo` hack.
+      - `zz-docker.conf`: workers run as `php-devforge`.
+      - The entrypoint adjusts uid/gid, fixes ownership, and no longer needs `sudo`.
+
+      **Two traps found while testing, both from the user asking the right questions**
+      - `usermod -u` does **not** chown files outside the home dir, and nvm lives in
+        `/usr/local/nvm`. Without an explicit chown, `nvm install` and global npm/pnpm
+        packages break — the container would start fine and fail later, confusingly.
+      - The ownership fix must run on **every start**, not only when the uid changes. A
+        named volume keeps the ownership it was created with: the existing
+        `dataphp-devforge` volume was still `www-data 700`, so workers could not
+        traverse `/home/php-devforge` and every page returned `File not found`.
+        `$HOMEDIR` also needs mode 755, because Apache is a different uid and still has
+        to traverse it.
+      - The recursive chown deliberately **excludes `public_html`** — that is the
+        mounted host folder, and a `chown -R` there would rewrite the ownership of the
+        user's real projects.
+
+      **Verified**: containers start; workers run as uid 1000 while the master stays
+      root; a file written by PHP over the web is owned by `yostinv` and deletable
+      without sudo; `pnpm install` leaves `node_modules` owned by you; `nvm install 22`
+      works (v22.23.2); `sudo` still works inside (the sudoers rule is by name, not
+      uid); all three host forms serve over HTTPS; it works from a wiped volume; and
+      with `PUID=1501` the user, `NVM_DIR` and created files all land on 1501.
+
+      README updated: the `sudo chown yourUser:www-data` step is gone.
+
+      **Unblocks task 7** — the installer can now create the projects folder with no
+      sudo at all.
+
+<details>
+<summary>Options considered (kept for the record)</summary>
 
 The problem this needs to solve: today the README tells users to run
 `sudo chown yourUser:www-data -R /home/php-devforge`. That is confusing for people
@@ -303,6 +398,11 @@ Options (**none chosen yet**):
 - macOS handling is different (Docker Desktop maps ownership automatically) — should
   the two platforms behave differently, or pick one approach that works for both?
 
+</details>
+
+**Still open:** none of this was tested on macOS. Docker Desktop maps ownership on its
+own there, so PUID/PGID should be harmless, but it is unverified — see task 15 (CI).
+
 ---
 
 ## 🟡 Quality and maintenance
 
@@ -9,11 +9,14 @@ x-logging: &json-logging
 x-phpconfig_default: &phpconfig_default
   volumes:
     - dataphp-devforge:/home/php-devforge
-    - /home/php-devforge/public_html:/home/php-devforge/public_html
+    - ${PROJECTS_DIR:-/home/php-devforge/public_html}:/home/php-devforge/public_html
     - ./.caroot:/caroot:ro
   environment:
     - PHP_XDEBUG=${XDEBUG_ENABLE}
     - XDEBUG_IDKEY=${XDEBUG_IDKEY}
+    # Files created in the container end up owned by this uid/gid on the host.
+    - PUID=${PUID:-1000}
+    - PGID=${PGID:-1000}
   logging: *json-logging
 
 services:
@@ -56,7 +59,7 @@ services:
     volumes:
       - dataphp-devforge:/home/php-devforge:ro
       - ./certificates:/etc/apache2/ssl/:ro
-      - /home/php-devforge/public_html:/home/php-devforge/public_html
+      - ${PROJECTS_DIR:-/home/php-devforge/public_html}:/home/php-devforge/public_html
     container_name: apachedev
     hostname: ${USERNAME}-apachedev
     environment:
 
@@ -33,8 +33,11 @@ function silly_mapper(r)
         local path_parts = {}
 
         if string.find(final_path, "%-%-") then
-            -- Usar separador --
-            for part in string.gmatch(final_path, "[^%-%-]+") do
+            -- Split on "--" only. "[^%-%-]+" would split on every single hyphen,
+            -- so a project named mi-app became sites/app/mi instead of sites/mi-app.
+            -- \1 cannot appear in a hostname, so it is a safe temporary separator.
+            local tmp = (final_path:gsub("%-%-", "\1"))
+            for part in string.gmatch(tmp, "[^\1]+") do
                 table.insert(path_parts, part)
             end
         else
 
@@ -60,9 +60,10 @@ RUN pecl install imagick redis apcu xdebug \
 # Instalar Composer
 COPY --from=composer:2 /usr/bin/composer /usr/bin/composer
 
-# Crear usuario php-devforge con UID/GID 33
-RUN /usr/sbin/useradd -g 33 -o -u 33 -c "php dev" -m -d /home/php-devforge -s /bin/bash php-devforge \
-    && sed -i -e "s/\\/var\\/www/\\/home\\/php-devforge/g" /etc/passwd
+# Dev user with its own group. 1000/1000 is the usual first user on Linux, so
+# most hosts need no adjustment; the entrypoint fixes it via PUID/PGID otherwise.
+RUN groupadd -g 1000 php-devforge \
+    && useradd -u 1000 -g php-devforge -c "php dev" -m -d /home/php-devforge -s /bin/bash php-devforge
 
 RUN echo 'php-devforge ALL=(ALL) NOPASSWD:ALL' > /etc/sudoers.d/php-devforge \
     && chmod 440 /etc/sudoers.d/php-devforge
@@ -102,5 +103,4 @@ RUN chmod +x /usr/local/bin/xdebug \
 
 COPY config_files/docker-php-ext-xdebug.ini "/usr/local/etc/php/mods-available/docker-php-ext-xdebug.ini"
 
-USER php-devforge
 WORKDIR /home/php-devforge