# Craft CMS reference

Reference for running Craft CMS on TurboStack: how to point Craft's cache and sessions at the platform's Redis, and how to run the background queue. For setup see [Deploy Craft CMS](deploy.md); for tuning see [Craft CMS best practices](best-practices.md).

## File layout

Your Craft codebase lives under your system user's home directory. `~` is that home directory (for example `/var/www/prod/`).

| Path | What it is |
| --- | --- |
| `~/public_html/` | Web document root |
| `~/craftcms/` | The Craft codebase |
| `~/craftcms/config/` | Configuration files (`general.php`, `app.php`, `project/`) |
| `~/craftcms/storage/` | Runtime data, caches and logs |

For ownership and permissions, see [Application file layout and permissions](../index.md#file-layout-and-permissions).

## Redis cache and sessions

TurboStack provisions Redis, but Craft only uses it once you point its cache and session components at it in `config/app.php`. Install the Redis driver first:

```bash
composer require yiisoft/yii2-redis
```

Then configure the components. This uses the cache instance for the data cache and the persistent instance for sessions, each on its own database index:

```php
<?php
use craft\helpers\App;

return [
    'components' => [
        // Connection to the Redis cache instance (unix socket)
        'redis' => [
            'class' => yii\redis\Connection::class,
            'unixSocket' => '/var/run/redis/redis.sock',
            'database' => 0,
        ],
        'cache' => [
            'class' => yii\redis\Cache::class,
            'defaultDuration' => 86400,
            'keyPrefix' => 'craft',
        ],
        // Sessions on the persistent instance, with its own database index
        'session' => function() {
            return Craft::createObject([
                'class' => yii\redis\Session::class,
                'as session' => craft\behaviors\SessionBehavior::class,
                'redis' => [
                    'class' => yii\redis\Connection::class,
                    'unixSocket' => '/var/run/redis-persistent/redis.sock',
                    'database' => 1,
                ],
            ]);
        },
    ],
];
```

- `unixSocket` replaces `hostname` and `port`; leave those out, because they are ignored when a socket path is set.
- Give each component its own `database` index. Craft warns that sharing an index lets one component flush another's data.
- The `session` component may also live in `config/app.web.php`, which Craft loads only for web requests. Either file works.

> [!NOTE]
> The two instances are the cache on `/var/run/redis/redis.sock` and the persistent instance on `/var/run/redis-persistent/redis.sock`. See [How to inspect Redis with Redis Insight](../../technologies/redis/inspect-with-redis-insight.md) for the instance and database layout.

## Background queue

Craft processes long tasks (image transforms, search indexing, emails) through a queue. By default it runs the queue on web requests, which adds load to PHP. On a busy site, turn that off and run the queue as a persistent worker instead.

Disable the web-triggered runner in `config/general.php`:

```php
'runQueueAutomatically' => false,
```

Then run Craft's queue as a [user system service](../../technologies/system-services/manage-user-services.md) so it restarts on failure and survives logout. Keep the number of workers within the host's processor budget (see [Scale throughput with more instances](../../technologies/system-services/manage-user-services.md#scale-throughput-with-more-instances)).

## Related

- [Deploy Craft CMS](deploy.md)
- [Craft CMS best practices](best-practices.md)
- [Troubleshooting Craft CMS](troubleshooting.md)
- [Application file layout and permissions](../index.md#file-layout-and-permissions)
- [How to manage user system services](../../technologies/system-services/manage-user-services.md)