You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
intro: 'How zero-downtime deploy tools structure releases, and which Statamic paths should live outside the release folder.'
5
+
intro: 'How zero-downtime deploy tools structure releases, and how to set up Statamic so the Stache cache and Git Automation work correctly with them.'
6
6
template: page
7
7
categories:
8
8
- development
9
9
- troubleshooting
10
10
---
11
11
## Understanding the folder structure
12
12
13
-
Zero downtime deployment services like [Laravel Forge](https://forge.laravel.com/), [Envoyer](https://envoyer.io/) and [Deployer](https://deployer.org/) typically use a multiple-release directory structure and symlinks to handle deployments.
13
+
Zero downtime deployment services like [Laravel Forge](https://forge.laravel.com/), [Envoyer](https://envoyer.io/), [Ploi](https://ploi.io/) and [Deployer](https://deployer.org/) typically use a multiple-release directory structure and symlinks to handle deployments.
14
14
15
15
For example, with Laravel Forge:
16
16
@@ -35,16 +35,19 @@ Every deployment has its own timestamped release directory, with a fresh clone o
35
35
After a successful deployment, the `current` folder is then symlinked to the latest release. This symlink swap is the secret sauce for zero downtime.
36
36
37
37
## Cache storage
38
+
38
39
Statamic's content management heavily relies on caching, and sometimes it's necessary for the [Stache](/stache) to store absolute file paths in your app's cache. This can lead to deployment errors when users are hitting your frontend, since each release [exists in a separate timestamped folder](#understanding-the-folder-structure).
39
40
40
41
The solution is simple. Just as you should never share a cache between different websites, you should never share a cache between your deployed releases.
41
42
42
43
### How to avoid sharing file cache
43
44
44
-
There are two ways to avoid sharing a file cache between your deployment releases:
45
+
There are three ways to avoid sharing a file cache between your deployment releases:
45
46
46
47
1. Some services, like Laravel Forge, may allow you to configure the "shared paths" between deployments. If your application allows for it, you could remove the `storage` directory from your site's shared paths, ensuring each release has its own `storage` folder.
48
+
47
49
2. Another option is to create a `cache` folder at the top level of your app, bypassing the shared `storage` folder. Configure your app to use a custom cache store location by changing `stores.file.path` in `config/cache.php`:
50
+
48
51
```php
49
52
'stores' => [
50
53
'file' => [
@@ -55,80 +58,231 @@ There are two ways to avoid sharing a file cache between your deployment release
55
58
],
56
59
```
57
60
61
+
This affects all file cache usage (rate limits, locks, queue locks, etc.), not just the Stache.
62
+
63
+
3. For a more targeted variant, give the Stache its own dedicated cache store. Laravel's default cache stays put. In `config/cache.php`, add a new store:
64
+
65
+
```php
66
+
'stores' => [
67
+
'stache' => [ // [tl! ++]
68
+
'driver' => 'file', // [tl! ++]
69
+
'path' => base_path('stache'), // [tl! ++]
70
+
'lock_path' => base_path('stache'), // [tl! ++]
71
+
], // [tl! ++]
72
+
],
73
+
```
74
+
75
+
Then in `config/statamic/stache.php`, point the Stache at the new store:
76
+
77
+
```php
78
+
'cache_store' => 'stache', // [tl! ++]
79
+
```
80
+
58
81
### How to avoid sharing Redis cache
59
82
60
-
To avoid sharing a Redis cache between your deployment releases, we recommend setting a cache prefix unique to each release on your filesystem. This can be configured by adding a `redis.cache.options.prefix` in `config/database.php`:
83
+
There are two ways to avoid sharing a Redis cache between your deployment releases:
This affects all Redis cache usage (rate limits, locks, queue locks, etc.), not just the Stache.
103
+
104
+
2. For a more targeted variant, give the Stache its own dedicated Redis cache store. Laravel's default Redis cache stays shared between releases, which is what you want for things like rate limits and queue locks.
105
+
106
+
In `config/database.php`, add a new Redis connection with a per-release prefix:
In `config/cache.php`, add a cache store using that connection:
125
+
126
+
```php
127
+
'stores' => [
128
+
'stache' => [ // [tl! ++]
129
+
'driver' => 'redis', // [tl! ++]
130
+
'connection' => 'stache', // [tl! ++]
131
+
], // [tl! ++]
132
+
],
133
+
```
78
134
79
-
If you plan to use Statamic's [Git Automation](/git-automation) feature alongside zero downtime deployments, you may need to tweak your deployment settings to enable git commits and pushes from each release folder.
135
+
Then in `config/statamic/stache.php`, point the Stache at the new store:
80
136
81
-
### Setting up a Git remote
137
+
```php
138
+
'cache_store' => 'stache', // [tl! ++]
139
+
```
140
+
141
+
:::tip
142
+
The `stache` connection above shares Redis database `1` with the default `cache` connection. Key prefixes keep their entries separate during normal use, but `php artisan cache:clear` wipes both. Point the `stache` connection at a different database (e.g. `'database' => env('REDIS_STACHE_DB', '2')`) for complete isolation, mirroring the file cache option above where the two stores naturally live in separate directories.
143
+
:::
144
+
145
+
## Git Automation
146
+
147
+
If you plan to use Statamic's [Git Automation](/git-automation) feature alongside zero downtime deployments, you'll need to set up a dedicated git clone for Statamic's content writes so they survive the symlink swap. See [Why this setup is needed](#why-this-setup-is-needed) at the end of this section for the full picture.
82
148
83
149
:::tip
84
-
Unlike other services, Laravel Forge will actually keep the `.git` folder around in each release, meaning you can skip this step.
150
+
Examples below use Laravel Forge syntax. The same concepts apply to Envoyer, Ploi, Deployer, or custom scripts; you'll need to adapt the platform-specific syntax.
85
151
:::
86
152
87
-
Most zero downtime deployment services, like [Envoyer](https://envoyer.io/) and [Deployer](https://deployer.org/) create releases _without_ a `.git` folder, which Statamic needs to commit and push content back to your repository.
153
+
### Prerequisites
154
+
155
+
Set a global git identity on the server. Autostash and rebase in [Updating your deploy script](#updating-your-deploy-script) need it:
Create a new `statamic` directory at the root of your site with a [sparse-checkout](https://git-scm.com/docs/git-sparse-checkout) clone inside it. The clone lives outside any release directory, giving Statamic's Git Automation a dedicated working tree where content writes can be committed and pushed reliably.
88
165
89
-
You can work around this by setting up a Git object right after the `Clone New Release` step of your deployment process:
166
+
The sparse-checkout list below covers the paths Statamic tracks by default. We'll wire `config/statamic/git.php` to point at this clone in [Configuring git paths](#configuring-git-paths) further down. Be sure to replace `your-site`, `your-org/your-repo`, and `your-branch` with your values:
Be sure to modify the above remote to point to your remote repository, along with the branch you wish to track.
190
+
:::tip
191
+
Form submissions are handled separately. See [Committing form submissions](#committing-form-submissions).
192
+
:::
100
193
101
-
### Preventing circular deployments
194
+
### Adding shared paths
102
195
103
-
If you plan on enabling automatic deployment when commits are pushed to your repository, you may wish to selectively disable deployments when Statamic pushes commits back to your repository.
196
+
In your deployment tool's shared paths configuration, add an entry for each path in the sparse-checkout list from [Setting up a Git remote](#setting-up-a-git-remote) above.
To do this, you will first need to append `[BOT]` to Statamic's commit messages [as documented here](/git-automation#customizing-commits). Once this is done, you can add a step to your deployment process to cancel the deployment when the commit message contains `[BOT]`.
213
+
In `config/statamic/git.php`, wrap every tracked path in an environment variable so the production paths stay configurable through `.env`. The defaults fall back to the standard Statamic locations when no variable is set.
106
214
107
215
```php
108
-
if [[ $FORGE_DEPLOY_MESSAGE =~ "[BOT]" ]]; then
109
-
echo "AUTO-COMMITTED ON PRODUCTION. NOTHING TO DEPLOY."
Then add the corresponding values to the site's `.env`, pointing each one at its path inside the `statamic` directory you created above. Be sure to replace `forge/your-site` with your site's path:
The deploy script below is an example for Laravel Forge with the new lines highlighted. Adapt the `$FORGE_*` variables and macros to your platform's equivalents.
248
+
249
+
```bash
250
+
$CREATE_RELEASE()
113
251
114
-
### Ensuring proper deployment hook order
252
+
cd$FORGE_RELEASE_DIRECTORY
115
253
116
-
When adding these steps to your deployment process, you should be mindful of the order in which they happen. Here's the order we recommend:
The pull runs before `stache:warm` so the Stache is warmed against the final content state. It brings in any content commits pushed from elsewhere, like edits made in a developer's local environment.
274
+
275
+
[`--autostash`](https://git-scm.com/docs/git-rebase#Documentation/git-rebase.txt---autostash) makes sure any in-flight writes in the Statamic clone, like a Control Panel edit Statamic's queue hasn't committed yet, survive the pull.
122
276
123
277
:::tip
124
-
If you're using [Static Caching](/static-caching), make sure you warm the cache _after_updating the current release, otherwise you'll be warming the wrong cache.
278
+
If you're using [Static Caching](/static-caching), make sure you warm the cache _after_activating the current release, otherwise you'll be warming the wrong cache.
125
279
:::
126
280
127
281
### Committing form submissions
128
282
129
-
If you plan on committing form submissions, you will need to store them outside the shared `storage` directory.
283
+
If you plan on committing form submissions, you will need to store them outside the shared `storage` directory.
130
284
131
-
To customize where form submissions are stored, add a `form-submissions` array to your `config/statamic/stache.php` config file:
285
+
First, customize where form submissions are stored by adding a `form-submissions` array to your `config/statamic/stache.php`:
132
286
133
287
```php
134
288
'stores' => [
@@ -139,20 +293,64 @@ To customize where form submissions are stored, add a `form-submissions` array t
139
293
],
140
294
```
141
295
142
-
After doing this, you will also need to update the tracked path for your submissions in`config/statamic/git.php`:
296
+
Then track the new path by adding an env-wrapped entry to`config/statamic/git.php`:
Finally, populate `forms/` in the Statamic clone and add a matching shared path. See steps 1 and 2 of [Adding paths later](#adding-paths-later).
311
+
312
+
### Adding paths later
313
+
314
+
To track and commit additional paths after the initial setup, follow the same order as the main flow:
315
+
316
+
1.**[Populate the path in the Statamic clone](#setting-up-a-git-remote):**
317
+
318
+
```bash
319
+
cd /home/forge/your-site/statamic
320
+
git sparse-checkout add <path>/
321
+
```
322
+
323
+
2. **[Add a new shared path](#adding-shared-paths)**.
324
+
325
+
3. **[Configure the git path](#configuring-git-paths)**.
326
+
327
+
### Preventing circular deployments
328
+
329
+
If you plan on enabling automatic deployment when commits are pushed to your repository, you may wish to selectively disable deployments when Statamic pushes commits back to your repository.
330
+
331
+
To do this, you will first need to append `[BOT]` to Statamic's commit messages [as documented here](/git-automation#customizing-commits). Once this is done, add the following at the very top of your deploy script, before the release is created, so the check happens before any deployment work is done:
332
+
333
+
```bash
334
+
if [[ $FORGE_DEPLOY_MESSAGE =~ "[BOT]" ]]; then
335
+
echo "AUTO-COMMITTED ON PRODUCTION. NOTHING TO DEPLOY."
336
+
exit 0
337
+
fi
338
+
```
339
+
340
+
### Why this setup is needed
341
+
342
+
Statamic's Git Automation tracks paths defined in [config/statamic/git.php](#configuring-git-paths) using helpers like `base_path('content')` and `resource_path('forms')`, which resolve to whichever release the running process is in. Without intervention, this creates two failure modes during zero-downtime deploys.
343
+
344
+
#### Silent skipped commits
345
+
346
+
A Control Panel edit during a deploy lands in the old release's content directory. After the symlink swap and queue restart, the queued commit job runs from the _new_ release, reads its path config against the new release's `base_path()`, finds a clean working tree, and exits without committing. No error is raised. When the old release is later cleaned up, the write is gone.
347
+
348
+
#### Push rejections
349
+
350
+
Each release ships with its own `.git/`. If something else pushes to origin (a developer pushing code, a second server, an overlapping worker from a previous release), the release's local history can fall behind origin and the push gets rejected:
351
+
352
+
```
353
+
error: failed to push some refs to '…'. Updates were rejected because the remote contains work that you do not have locally.
354
+
```
355
+
356
+
[Shared paths](#adding-shared-paths) fix the first by routing writes to a persistent location outside any release, so Statamic's commits always see them. The dedicated [Statamic clone](#setting-up-a-git-remote) fixes the second by giving Statamic a single `.git/` that persists across deploys instead of being a fresh clone every time. The [deploy script's `git pull`](#updating-your-deploy-script) resyncs it with any external commits at deploy time.
0 commit comments