Claude skill to setup Magento 2 on Warden in no time

If you are tired of wasting hours of your time setting up Magento2 locally, all you have to do is copy and paste this skill.

1. First of all, create the directory

mkdir -p ~/.claude/skills/magento-warden-init

2. Copy the following

---
name: magento-warden-init
description: Sets up a Warden environment for an existing Magento 2 project in this folder (PHP, MariaDB, OpenSearch, Redis, RabbitMQ, Varnish), configures app/etc/env.php and imports the database dump. Use when the user asks to create/initialize a Warden environment for Magento.
---

This skill exists to repeat the SAME procedure every time, without researching or improvising configuration. Follow the steps in order. If a required piece of information is missing, STOP and ask the user — do not guess.

**Communicate every step as you do it**: before running a command from this procedure, write a short line stating which step you're on (e.g. "Importing the database", "Creating the admin user"). Do not run several steps silently and summarize at the end — the user needs to follow progress step by step in real time, not just read a final recap.

This procedure can also be resumed halfway through (e.g. environment already created, db already imported): check the actual state before re-running a step that's already done (e.g. check if `vendor/` exists before rerunning composer, if tables are already populated before reimporting the db, if `admin_user` already has rows before creating the admin user) and only run the missing steps, still communicating which ones you're skipping because they're already done and which ones you're running.

## Fixed rules (never change)

- Composer must ALWAYS run inside the Warden container (`warden env exec -T php-fpm composer ...`), NEVER on the host.
- Do not touch, stop, or recreate Docker resources belonging to other Warden projects on the machine. `warden sign-certificate` and other `svc`-level commands reconnect the shared `traefik` container to all active environments: that's normal and not a problem, but you must not do anything else that affects other projects (no `docker system prune`, no removing networks/volumes that don't belong to this project).
- The Warden environment type to use is always `magento2` (it already includes nginx, varnish, php-fpm, mariadb, opensearch, redis, rabbitmq — don't add/configure these services manually).
- The default DB credentials for `WARDEN_ENV_TYPE=magento2` are **`root` / `magento`**, database **`magento`**, host **`db`** (defined in Warden's `environments/magento2/db.base.yml`, overriding the generic `app/app/app` default). Use these unless the user specifies different credentials.
- Official reference: https://docs.warden.dev/environments/magento2.html — when in doubt about a Warden command, check that, don't search elsewhere.
- If the project already has an `app/etc/env.php` file (or a template like `env copy.php` / `env.php.sample`), use it as a MODEL for the new `env.php`: don't invent the structure, copy the existing one and only update the values that change (service hosts, domain, credentials, crypt key if needed).

## PHP / Magento version compatibility (verified, don't re-research)

- Magento 2.4.6 (including patches up to p13): requires PHP **~8.1 or ~8.2**. Does NOT support 8.3 despite some sources claiming otherwise — verified empirically with composer install.
- Magento 2.4.7: PHP ~8.1, ~8.2, ~8.3.
- Magento 2.4.8: PHP **~8.3 or ~8.4**. No longer supports Elasticsearch, only OpenSearch.
- OpenSearch: use **2.12** as default — compatible with both 2.4.6 and 2.4.8.
- If the project will need a future Magento upgrade (e.g. 2.4.6 → 2.4.8), pick NOW the PHP version compatible with the Magento version currently in composer.json, and tell the user it will need to change at upgrade time.

## Procedure

1. **Verify you're in the right folder**: the working directory must be the root of the Magento project (must contain `composer.json` with `magento/product-community-edition` or `magento/product-enterprise-edition`). If not, stop and ask for path confirmation.

2. **Gather the required information** (ask all of it at once with AskUserQuestion if not already provided in the user's message):
   - Project/environment name (`WARDEN_ENV_NAME`, also becomes the `<name>.test` domain)
   - PHP version — infer the default from the Magento version in `composer.json` (see table above) and propose it as a recommendation, but let the user choose
   - MariaDB/MySQL version (recommended default: MariaDB 10.6)
   - Extra services beyond the base ones (Varnish, RabbitMQ — ask if needed, the `magento2` type enables them by default)
   - Path to the database dump to import (if it already exists in the project, detect it automatically, e.g. `.sql`, `.sql.gz`, `.gz` files in the root — otherwise ask)
   - Whether an `env.php` template exists in the repo (`app/etc/env copy.php`, `env.php.sample`, etc.) or whether it needs to be created from scratch
   - Crypt key to use in `env.php` (if the user doesn't provide one, ask explicitly — don't generate one randomly without asking)
   - Admin user credentials (username, password, email, first name, last name)

3. **Create the environment**:
   ```
warden env-init <name> magento2
   ```
   Confirm overwrite if prompted. This already creates a `.env` with the correct defaults for the `magento2` type (PHP, MariaDB, OpenSearch 2.12, Redis, RabbitMQ, Varnish). Then edit `.env` ONLY for the specific values decided in step 2 (PHP_VERSION, MYSQL_DISTRIBUTION_VERSION, etc.) — don't rewrite the file from scratch.

4. **Sign the certificate and start**:
   ```
warden sign-certificate <name>.test
warden env up -d
   ```

5. **Before running composer, check credentials**: Warden mounts the host's `~/.composer` inside the container, so `composer` will already use the host's `~/.composer/auth.json` (with the user's machine credentials) with no extra steps needed. However, check whether the project root has a real `auth.json` file (NOT `auth.json.sample`/`auth.json.dist`, which are just empty templates) with filled-in credentials:
   - If a project `auth.json` with real credentials exists, add/update the corresponding entries in the host's `~/.composer/auth.json`, without deleting credentials already present for other hosts/projects. If different credentials already exist for the same host, stop and ask which ones to use before overwriting.
   - If no real project `auth.json` exists (only `.sample`/`.dist` or none at all), don't ask anything: proceed directly with composer, using the credentials already present in the host's `~/.composer/auth.json`.

6. **Composer install** (always inside the container, never on the host):
   ```
warden env exec -T php-fpm composer install
   ```
   If commercial packages fail with 404/403 errors from `repo.magento.com` or other private repositories: this is not necessarily a temporary issue. Verify with a direct request (curl with the same credentials from `~/.composer/auth.json`, which Warden mounts from the host) whether the response is 403 (license/entitlement issue) or actually temporary. If it's a license issue, stop and ask the user how to proceed (contact whoever manages the project for credentials, or temporarily remove the package).

7. **Configure `app/etc/env.php`**:
   - Use the existing template in the repo if present.
   - Update: service hosts to match the Warden docker-compose ones (`db`, `redis`, `opensearch` — verify the exact active service names with `warden env exec -T php-fpm getent hosts db redis opensearch`), domain (`<name>.test`), DB credentials (see above), crypt key.
   - Don't change other values from the template unless the user asks.

8. **Import the database**:
   - `.sql` file: `cat dump.sql | warden db import`
   - `.sql.gz` / `.gz` file: `zcat dump.sql.gz | warden db import` (or `gunzip -c` on macOS if `zcat` isn't available)
   - Verify at the end with `warden env exec -T db mysql -uroot -pmagento -e "SHOW TABLES;" magento` (adjust credentials/db name if different from what was decided in step 2/7).

9. **ALWAYS update the domain in `core_config_data` after import** (mandatory step, don't skip it and don't ask whether to do it):
   - Check all rows with `path LIKE '%base_url%'` (in the `core_config_data` table) for every scope/scope_id (default, websites, store views — not just scope `default`/scope_id 0), e.g.:
     ```
     SELECT config_id, scope, scope_id, path, value FROM core_config_data WHERE path LIKE '%base_url%';
     ```
   - Update `web/unsecure/base_url` and `web/secure/base_url` (and any `base_link_url`, `base_static_url`, `base_media_url` present) to the new `.test` domain created by Warden, **for every occurrence found**, including any subdomains or additional stores/websites (e.g. if the old domain was `www.example.com` and there's also a `blog.example.com` subdomain or a second store on `shop.example.com`, both need to be mapped to consistent `.test` subdomains, e.g. `blog.<name>.test`, `shop.<name>.test` — ask the user how they want the subdomains named if it's not obvious).
   - Then do a general search for the old domain across the whole table to find any other leftover references:
     ```
     SELECT config_id, scope, scope_id, path, value FROM core_config_data WHERE value LIKE '%olddomain%';
     ```
   - For every other occurrence found (logo, email, external service URLs, etc.) do NOT change it automatically: list it for the user and ask whether it should be updated or left as-is (company email addresses, for instance, normally shouldn't be touched).

10. **Always create an admin user** after importing the database, inside the php-fpm container, using the credentials gathered in step 2:
   ```
warden env exec -T php-fpm bin/magento admin:user:create \
--admin-user="<username>" \
--admin-password="<password>" \
--admin-email="<email>" \
--admin-firstname="<firstname>" \
--admin-lastname="<lastname>"
   ```
   If a user with that email/username already exists in the imported DB, flag it and ask whether to update the password instead of creating a new one.

11. **Always run these commands** inside the php-fpm container, in this order, after creating the admin user:
   ```
warden env exec -T php-fpm bin/magento config:set --lock-env dev/static/sign 0
warden env exec -T php-fpm bin/magento deploy:mode:set -s developer
warden env exec -T php-fpm bin/magento cache:disable block_html full_page
   ```

12. **Summarize** for the user what was done and what's left (e.g. `bin/magento setup:upgrade`, `setup:di:compile`) — don't run these extra steps unless explicitly requested.

## When to stop and ask

- The DB dump is missing and there's no recognizable file in the project root.
- The PHP version the user requested is incompatible with the Magento version in composer.json (flag it, don't silently proceed).
- Credentials/private repositories fail and it's unclear whether it's a license issue or a temporary one.
- The project already has an existing Warden environment (`.env` with `WARDEN_ENV_NAME` already set) — ask whether it should be overwritten.

3. And that’s it. Now in your project root you can just type /magento-warden-init and have the complete setup