**Prerequisites:**

- PHP 8.1+ with required extensions
- MySQL, MariaDB, or PostgreSQL
- SSH or SFTP access to your server
- A DeployHQ account

## What is Joomla?

Joomla is a mature, open-source CMS that powers millions of websites worldwide. It sits between WordPress (simpler) and Drupal (more complex) in terms of capability and learning curve. Joomla excels at multi-language sites, complex content hierarchies, and access control.

## Project Structure

```
joomla/
├── administrator/       # Admin panel
│   ├── components/
│   ├── modules/
│   └── templates/
├── components/          # Frontend components
├── modules/             # Frontend modules
├── plugins/             # System plugins
├── templates/           # Frontend templates
│   └── my-template/
├── media/               # CSS, JS, images
│   └── plg_*/           # Plugin media (auto-generated)
├── cache/               # ⚠️ Exclude
├── tmp/                 # ⚠️ Exclude
├── configuration.php    # ⚠️ Environment-specific, exclude
├── .htaccess
└── web.config
```

## Version Control Options

### Option A: Full Joomla in Git (Small Sites)

Track the entire installation. Exclude environment-specific files:

**.gitignore:**
```gitignore
configuration.php
cache/
tmp/
logs/
media/plg_*
administrator/cache/
```

### Option B: Template/Extension Only (Recommended)

Track only your custom template or extension in Git:

```
my-joomla-template/
├── css/
├── js/
├── html/           # Template overrides
├── images/
├── index.php
├── templateDetails.xml
└── error.php
```

Deployment path: `/var/www/html/templates/my-joomla-template/`

## Deploy with DeployHQ

### Full Site Deployment

- **Deployment Path:** `/var/www/html/`
- **Excluded Files:** `configuration.php`
- **Shared Paths:** `configuration.php`, `images/` (user uploads), `cache/`, `tmp/`, `logs/`

### Template-Only Deployment

- **Deployment Path:** `/var/www/html/templates/my-template/`
- **No exclusions needed** — the template directory is self-contained

### Build Commands (If Using Asset Compilation)

```bash
cd %path% && npm ci && npm run build
```

Most Joomla templates don't require build tools, but modern templates may use SCSS or Tailwind CSS.

### Post-Deployment

Clear Joomla's cache:
```bash
rm -rf /var/www/html/cache/* /var/www/html/administrator/cache/*
```

Or via Joomla CLI:
```bash
php /var/www/html/cli/joomla.php cache:clean
```

## Multi-Environment Setup

| Branch | Server | Configuration |
|--------|--------|---------------|
| `main` | Production | `configuration.php` with production DB |
| `staging` | Staging | Separate `configuration.php` with staging DB |

Keep `configuration.php` on each server and exclude it from deployment.

## Troubleshooting

### Extension Conflicts After Deployment

If deploying third-party extensions alongside custom code, Joomla's update system may conflict. Best practice: manage third-party extensions through Joomla's admin panel, deploy only custom code through DeployHQ.

### Database Schema Updates

Joomla extensions define database changes in their XML manifest. After deploying a new extension version, run the extension's installer through the admin panel to apply schema changes:

**System** → **Extensions** → **Discover** → **Install**

### .htaccess Overwritten

If your deployment includes `.htaccess` but the server needs custom rules, either:
- Include the server-specific rules in your Git `.htaccess`
- Exclude `.htaccess` from deployment and manage it on the server

## Conclusion

Joomla's PHP-based architecture deploys cleanly via SFTP or SSH. Whether you're deploying a full installation or just a custom template, DeployHQ handles the file transfer and keeps your `configuration.php` safe.

[Sign up for DeployHQ](https://www.deployhq.com/signup) — free for one project.

Questions? Contact [support@deployhq.com](mailto:support@deployhq.com) or on [Twitter/X](https://x.com/deployhq).