Server Directory Structure and Data Locations

In Seravo's hosting environment, website code, databases, and configuration files are organized into standardized paths. This consistent structure enables automated server-level monitoring, performance optimizations, and backups.

All sites use the open-source Seravo WordPress project template as their default installation base. It is Composer-driven and derived from the Roots Bedrock architecture.

Data Persistence (`/data/`)

All site-specific data resides under the /data/ directory.

During system updates and container maintenance, the site's runtime environment is periodically rebuilt from a clean image. Only the contents of the /data/ directory are preserved. Never store site files or custom scripts in default operating system directories (such as /var/ or /tmp/).

The SSH user's actual home directory is located at /data/home/$USER/. Symlinks are configured automatically, allowing you to use the standard ~/ path in your terminal sessions as usual.

Key Paths and Directories

Directory or File	Description and Purpose
`/data/wordpress/`	Project root. Location of version control (Git), Composer (`composer.json`), Docker configurations, and development tools.
`/data/wordpress/htdocs/`	Web root. The public directory from which the HTTP server (nginx) serves the website.
`/data/wordpress/htdocs/wordpress/`	WordPress Core. Core WordPress files, which can also be managed via Composer. Never modify these files directly by hand.
`/data/wordpress/htdocs/wp-content/`	Site application code. Themes, plugins, must-use plugins (mu-plugins), and language packs.
`/data/wordpress/htdocs/wp-content/uploads/`	Uploads and media files. Reserved exclusively for user-uploaded media. This directory should not be tracked in Git.
`/data/wordpress/nginx/`	Nginx server configurations. Custom HTTP server rules (`*.conf` files).
`/data/log/`	Server logs. Site log files (nginx access and error logs, PHP-FPM, WordPress debug, SSH events).

Default Project Structure

In Seravo's project layout, application code is separated from WordPress Core. This allows clean dependency management with Composer and clean version control without tracking core files in Git.

The project layout under /data/wordpress/:

/data/wordpress
├── config.yml                  # Development settings (copied from config-sample.yml)
├── config-sample.yml           # Example configuration for development environments
├── composer.json               # PHP dependencies (plugins, themes, WordPress Core)
├── composer.lock
├── docker-compose.yml          # Local Docker development environment configuration
├── Vagrantfile                 # Vagrant support for local development (legacy)
├── package.json                # Node/npm dependencies and build scripts
├── gulpfile.js                 # Build tool configuration example
├── phpcs.xml                   # PHP_CodeSniffer coding standards
├── nginx/                      # Custom nginx server rules
│   └── custom.conf             # Custom redirects and configurations (*.conf)
├── scripts/                    # Helper scripts, CI tools, and Git hooks
│   ├── hooks/                  # E.g., pre-commit and post-receive hooks
│   ├── run-tests               # Test runner for local and CI environments
│   └── WordPress/Installer.php # Composer installation helper
├── vendor/                     # Composer-managed PHP packages
└── htdocs/                     # Public web root
    ├── index.php
    ├── wp-config.php           # WordPress configuration file
    ├── wordpress/              # WordPress Core (wp-admin, wp-includes, etc.)
    └── wp-content/             # Site-specific application code
        ├── mu-plugins/         # Must-use plugins (including Seravo Plugin)
        ├── plugins/            # Plugins (managed via Composer or custom)
        ├── themes/             # Themes
        ├── languages/          # Translation files
        └── uploads/            # Media files (excluded from Git)

Media Files (`uploads/`) and Development Environments

All user-uploaded media belongs exclusively in /data/wordpress/htdocs/wp-content/uploads/.

Theme and plugin assets (icons, stylesheets, background images) should be stored within their respective theme or plugin directories (e.g., wp-content/themes/theme-name/assets/), never in uploads/.
Production media files and database dumps should never be tracked in Git.

When developing locally inside Seravo's Docker container, you do not need to download the entire production uploads/ directory to your local machine. The development container uses an automatic asset proxy that fetches missing media files on demand directly from the production site, provided the production domain is defined in config.yml. The production database can be pulled into your local container using the command wp-pull-production-db.

Prerequisites for Seravo Automation and Monitoring

To ensure Seravo's 24/7 automated monitoring, security updates, and performance optimizations function reliably, the environment requires the following paths and endpoints:

WordPress Core: Must reside in /data/wordpress/htdocs/wordpress/.
Application Code and Content: Themes, plugins, and uploads must be located in /data/wordpress/htdocs/wp-content/.
Admin Dashboard: The WordPress admin dashboard must be accessible at [https://example.com/wp-admin/](https://example.com/wp-admin/). If you customize your login URL, the default /wp-admin/ location must remain functional in parallel.
Automated Image Optimization: Seravo's background optimization service processes images located strictly within /data/wordpress/htdocs/wp-content/uploads/. Images in other directories are left untouched to prevent unintentional modifications to theme or core files.
Heartbeat Monitoring: Seravo monitors site availability and vital processes via [https://example.com/wp-admin/admin-ajax.php?action=heartbeat](https://example.com/wp-admin/admin-ajax.php?action=heartbeat). If this endpoint is blocked or removed, automated health checks cannot evaluate site status accurately.

Alternative Directory Layouts

If your project utilizes a custom file structure, it can be adapted to Seravo using symbolic links (symlinks), as long as the paths expected by the server remain accessible.

Adapting Roots Bedrock

Roots Bedrock uses web/ as its public web root, web/wp/ for WordPress Core, and web/app/ for content. To make a Bedrock project compatible with Seravo, you can use either of the following approaches:

Option A: Configuring Paths in `composer.json` (Recommended)

The cleanest approach is to configure Bedrock's composer.json to install WordPress and plugins directly into Seravo's default paths. This eliminates the need for symlinks entirely:

"extra": {
  "installer-paths": {
    "htdocs/wp-content/mu-plugins/{$name}/": ["type:wordpress-muplugin"],
    "htdocs/wp-content/plugins/{$name}/": ["type:wordpress-plugin"],
    "htdocs/wp-content/themes/{$name}/": ["type:wordpress-theme"]
  },
  "wordpress-install-dir": "htdocs/wordpress"
}

Option B: Adapting Standard Bedrock Using Symlinks

If you prefer to maintain Bedrock's original directory layout, create the required symbolic links in the project root (/data/wordpress/) so that Seravo's background services can locate the necessary paths:

cd /data/wordpress

# 1. Link the web root
ln -s web htdocs

# 2. Link the content directory (app -> wp-content)
ln -s app web/wp-content

# 3. Link WordPress Core (wp -> wordpress)
ln -s wp web/wordpress

# 4. Ensure the nginx configuration directory exists
mkdir -p nginx

Important: Do Not Hardcode Database Credentials in .env

Seravo's server environment exposes database credentials (DB_NAME, DB_USER, DB_PASSWORD, DB_HOST) automatically as system environment variables.

Leave these variables undefined or empty in your production .env file so that Bedrock retrieves them directly from the server environment (getenv()). If credentials are hardcoded into .env, the database connection will break when Seravo's automation updates database containers or rotates passwords.

Deployment Tools (Deployer, Capistrano, GitHub Actions)

If you use a deployment tool that deploys releases into timestamped directories (releases/<timestamp>/) and activates them by switching a symlink, ensure your deployment pipeline maintains the standard paths required by Seravo.

The server container, nginx routing, and maintenance scripts require the existence of these five paths:

/data/wordpress/
/data/wordpress/htdocs/
- Note: wp-config.php must reside in or be symlinked directly from this directory.
/data/wordpress/htdocs/wordpress/
/data/wordpress/htdocs/wp-content/
/data/wordpress/nginx/

Layout with Deployment Releases

A dependable deployment architecture stores persistent assets (such as user uploads, configurations, and server rules) inside a shared/ directory, while linking htdocs to the active release:

/data/wordpress
├── releases/
│   ├── 20261110090000/
│   └── 20261111120000/
│       ├── web/                        # Public release directory
│       │   ├── index.php
│       │   ├── wp-config.php -> /data/wordpress/shared/wp-config.php
│       │   ├── wordpress/              # WordPress Core
│       │   └── wp-content/
│       │       ├── plugins/
│       │       ├── themes/
│       │       └── uploads -> /data/wordpress/shared/uploads/
│       └── ...
├── current -> releases/20261111120000/  # Points to the active release
├── htdocs -> current/web/              # Required web root for nginx
├── nginx/                              # Required path for nginx rules
│   └── custom.conf                     # Can be symlinked, e.g., from current/nginx/
└── shared/                             # Persistent data across releases
    ├── wp-config.php
    └── uploads/                        # User media files

Key Considerations for Deployment Pipelines:

htdocs Symlink: Seravo's nginx is configured to serve content strictly from /data/wordpress/htdocs/. Creating a symlink htdocs -> current/web/ (or current/htdocs/) allows atomic deployments without downtime.
wp-config.php: The configuration file must resolve directly inside the htdocs root. Typically, it is kept in shared/ and symlinked into each release during deployment.
Nginx Configurations (/data/wordpress/nginx/): The web server reads configuration snippets directly from this folder. If you track *.conf files in your repository, configure your deployment script to copy or symlink them into /data/wordpress/nginx/ and trigger wp-restart-nginx.
Uploads Directory (uploads/): Ensure that wp-content/uploads/ in every release is a symlink pointing to the persistent directory (shared/uploads/), ensuring media files remain intact across code deployments.

Git Version Control on the Server

Git repositories should always be initialized in /data/wordpress/.

Seravo's maintenance and update scripts automatically detect the presence of a Git repository. Any changes made by server maintenance are committed cleanly into version control, preventing file conflicts and ensuring your code is not overwritten during subsequent deployments.