claude-websimple-devops/references/wp-project.md

WP Project

Use this reference for WordPress-specific Websimple project conventions. For host environment, Docker, Traefik, protocol, or domain assumptions, see websimple-stack.md.

Config values used here

These environment variables drive WordPress project value derivation:

• WP_LOCAL_ROOT_PATH: shared local WordPress root path served by wp-apache2.
• WEBSIMPLE_STACK_PROTOCOL: stack-level protocol used to build local WordPress URLs.
• WEBSIMPLE_STACK_DOMAIN: stack-level domain suffix used to build local WordPress URLs.

Read these from the environment. Do not hard-code them in commands or examples; if any are missing when needed, ask the user to export them before proceeding.

Slug

A Websimple WordPress project is identified by a unique slug derived from its production domain.

Example:

• www.example.com → example

Local WordPress site

For a WordPress project ${slug}:

• Local project path: ${WP_LOCAL_ROOT_PATH}/${slug}. In the current websimple-stack this normally maps to ${DOCKER_DATA}/wp/sites/${slug} on the host and /var/www/html/${slug} in containers.
• Local database name: wp_${slug}
• Local site URL: ${WEBSIMPLE_STACK_PROTOCOL}://${slug}.${WEBSIMPLE_STACK_DOMAIN}
• Git repository URL: https://gitea.websimple.com/wp-sites/${slug}

Remote WordPress site

Use the corresponding Gitea repository Actions variables as the source of truth for the remote production environment:

• WP_SITE_URL: production site URL source of truth, including protocol.
• REMOTE_HOST
• REMOTE_PORT
• REMOTE_USER
• REMOTE_PATH

wp-sites repositories may rely on organization/repository fallback variables or secrets for REMOTE_* deployment values. If a per-repository REMOTE_HOST, REMOTE_PORT, REMOTE_USER, or REMOTE_PATH variable is missing, check the relevant fallback variable/secret source before treating the project metadata as incomplete or attempting to infer SSH values from the public site URL.

Prefer WP_SITE_URL for the production site URL. Reading it from repository variables is cheaper and avoids unnecessary remote SSH work. WP_SITE_URL must include the protocol, for example https://www.example.com.

Normally, the local user has SSH access to ${REMOTE_USER}@${REMOTE_HOST} on ${REMOTE_PORT} after repository values and fallback variables/secrets are resolved.

Only perform read-only actions on the remote host. Do not modify files, run updates, change options, write database data, deploy code, or execute destructive commands unless a future workflow explicitly adds a reviewed approval path.

If WP_SITE_URL is missing, determine the production site URL from the remote WordPress environment by running WP-CLI read-only from ${REMOTE_PATH}:

ssh -p "${REMOTE_PORT}" "${REMOTE_USER}@${REMOTE_HOST}" 'cd "${REMOTE_PATH}" && wp option get siteurl'

Treat that siteurl value as the fallback production site URL. It should include the protocol.