tonyair/silverstripe-framework
1
0
Fork 0
mirror of https://github.com/silverstripe/silverstripe-framework synced 2024-10-22 12:05:37 +00:00
Code Issues Projects Releases Wiki Activity

DOCS Clearer sysadmin guidance for "packaging" (#9960)

Browse Source 
* DOCS Clearer sysadmin guidance for "packaging"

We have all kinds of fun fallbacks that attempt to create supporting files in production environments.
The latest point of contention is dev/build automatically creating files in .graphql/ and public/_graphql/
if those don't exist. That should be regarded as a last resort option to allow introduction of GraphQL v4 in the CMS 4.x release line.
At least since CMS 4.1, we need some form of "packaging" for generated files (public/_resources),
or committing these into the codebase, so let's call that out for anyone running CMS infra.

* Add trailing slash

Co-authored-by: Aaron Carlino <unclecheese@leftandmain.com>
This commit is contained in:
Ingo Schommer 2021-06-02 10:59:42 +12:00 committed by GitHub
parent a3df66860f
commit fa3c5e6fea
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 37 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
docs/en/00_Getting_Started/00_Server_Requirements.md
View File

@ -65,8 +65,21 @@ hosting via the `public/`. See [4.1.0 upgrading guide](/changelogs/4.1.0).
### Filesystem permissions
SilverStripe needs write access for the webserver user to `public/assets`,
and read access for that user on everything else in your webroot.
During runtime, Silverstripe needs read access for the webserver user to your base path (including your webroot).
It also needs write access for the webserver user to the following locations:
* `public/assets/`: Used by the CMS and other logic to [store uploads](/developer_guides/files/file_storage)
* `TEMP_PATH`: Temporary file storage used for the default filesystem-based cache adapters in
[Manifests](/developer_guides/execution_pipeline/manifests), [Object Caching](/developer_guides/performance/caching)
and [Partial Template Caching](/developer_guides/templates/partial_template_caching).
See [Environment Management](/getting_started/environment_management).
If you aren't explicitly [packaging](#building-packaging-deployment)
your Silverstripe project during your deployment process,
additional write access may be required to generate supporting files on the fly.
This is not recommended, because it can lead to extended execution times
as well as cause inconsistencies between multiple server environments
when manifest and cache storage isn't shared between servers.
### Assets
@ -85,10 +98,10 @@ through SilverStripe, so is considered a second line of defence.
Files can be kept in draft stage,
and access restricted to certain user groups.
These files are stored in a special `.protected` folder (defaulting to `public/assets/.protected`).
These files are stored in a special `.protected/` folder (defaulting to `public/assets/.protected/`).
**Requests to files in this folder should be denied by your webserver**.
Requests to files in the `.protected` folder
Requests to files in the `.protected/` folder
are routed to PHP by default when using Apache, through `public/assets/.htaccess`.
If you are using another webserver, please follow our guides to ensure a secure setup.
See [Developer Guides: File Security](/developer_guides/files/file_security) for details.
@ -119,7 +132,7 @@ app/
Don't forget to include this additional folder in any syncing and backup processes!
### Building, Packaging and Deployment
### Building, Packaging and Deployment {#building-packaging-deployment}
It is common to build a SilverStripe application into a package on one environment (e.g. a CI server),
and then deploy the package to a (separate) webserver environment(s).
@ -135,7 +148,7 @@ to trigger and include in a deployment package:
See [Templates: Requirements](/developer_guides/templates/requirements#exposing-assets-webroot).
* `.graphql/` and `public/_graphql/`: Schema and type definitions required by CMS and any GraphQL API endpoint. Generated through
[silverstripe/graphql v4](https://github.com/silverstripe/silverstripe-graphql).
Triggered by `dev/build`, or [GraphQL Schema Build](/developer_guides/graphql/getting_started/building_the_schema).
Triggered by `dev/build`, or a [GraphQL Schema Build](/developer_guides/graphql/getting_started/building_the_schema).
* Various recipes create default files in `app/` and `public/` on `composer install`
and `composer update` via
[silverstripe/recipe-plugin](https://github.com/silverstripe/recipe-plugin).
@ -198,10 +211,10 @@ See [silverstripe/vendor-plugin](https://github.com/silverstripe/vendor-plugin)
### Caches
Silverstripe relies on various [caches](https://docs.silverstripe.org/en/4/developer_guides/performance/caching/)
Silverstripe relies on various [caches](/developer_guides/performance/caching/)
to achieve performant responses. By default, those caches are stored in a temporary filesystem folder,
and are not shared between multiple server instances. Alternative cache backends such as Redis can be
[configured](https://docs.silverstripe.org/en/4/developer_guides/performance/caching/).
[configured](/developer_guides/performance/caching/).
While cache objects can expire, when using filesystem caching the files are not actively pruned.
For long-lived server instances, this can become a capacity issue over time - see

2
docs/en/00_Getting_Started/03_Environment_Management.md
View File

@ -120,3 +120,5 @@ SilverStripe core environment variables are listed here, though you're free to d
| `SS_DATABASE_SSL_CA` | Absolute path to SSL Certificate Authority bundle file |
| `SS_DATABASE_SSL_CIPHER` | Optional setting for custom SSL cipher |
| `SS_FLUSH_ON_DEPLOY` | Try to detect deployments through file system modifications and flush on the first request after every deploy. Does not run "dev/build", but only "flush". Possible values are `true` (check for a framework PHP file modification time), `false` (no checks, skip deploy detection) or a path to a specific file or folder to be checked. See [DeployFlushDiscoverer](api:SilverStripe\Core\Startup\DeployFlushDiscoverer) for more details.<br /><br />False by default. |
| `TEMP_PATH`: Temporary file storage used for the default cache adapters in [Manifests](/developer_guides/execution_pipeline/manifests), [Object Caching](/developer_guides/performance/caching)
and [Partial Template Caching](/developer_guides/templates/partial_template_caching)|

2
docs/en/02_Developer_Guides/01_Templates/11_Partial_Template_Caching.md
View File

@ -186,6 +186,8 @@ SilverStripe\Core\Injector\Injector:
defaultLifetime: 3600
```
See [Execution pipeline: Manifests](/developer_guides/execution_pipeline/manifests) for storage of compiled templates.
### Nested cached blocks
Every nested cache block is processed independently.

11
docs/en/02_Developer_Guides/16_Execution_Pipeline/02_Manifests.md
View File

@ -11,6 +11,13 @@ Manifests help to cache information which is too expensive to generate on each r
Some manifests generate maps, e.g. class names to filesystem locations.
Others store aggregate information like nested configuration graphs.
Manifests are immutable for a given revision of the codebase,
and hence should be [packaged](/server_requirements#building-packaging-deployment) during deployment.
[Object Caching](/developer_guides/performance/caching)
and [Partial Template Caching](/developer_guides/templates/partial_template_caching)
are examples of mutable caches outside of manifests,
which need to be generated and expired during runtime.
## Storage
By default, manifests are serialised and cached via a cache generated by the [ManifestCacheFactory](api:SilverStripe\Core\Cache\ManifestCacheFactory).
@ -58,7 +65,9 @@ a `tests/` folder, unless tests are executed.
## Theme Manifests
The [ThemeManifest](api:SilverStripe\View\ThemeManifest) class builds a manifest of all templates present in a directory,
in both modules and themes. Templates in `tests/` folders are automatically excluded.
in both modules and themes.
Templates in `tests/` folders are automatically excluded.
The chapter on [template inheritance](../templates/template_inheritance) provides more details
on its operation.

2
docs/en/02_Developer_Guides/16_Execution_Pipeline/index.md
View File

@ -70,6 +70,8 @@ and determines the controller, action and any argument to be used ([Routing](../
further filtering before content is sent to the end user
* The response is output to the client
See [App Object and Kernel](app_object_and_kernel) for details.
## Request Preprocessing and Postprocessing
The framework provides the ability to hook into the request both before and