Skip to content
Merged
Show file tree
Hide file tree
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
143 changes: 143 additions & 0 deletions docs/ai_actions/img/diagram_source/server_setup.xml

Large diffs are not rendered by default.

4 changes: 2 additions & 2 deletions docs/getting_started/install_with_ddev.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ ddev config --database=postgres:14
To use MySQL instead, run the following command:

```bash
ddev config --database=mysql:8.0
ddev config --database=mysql:8.4
```

You can also use other versions of MariaDB, Mysql or PostgreSQL.
Expand Down Expand Up @@ -415,7 +415,7 @@ If the local project needs to answer to real production domains (for example, to

You can use DDEV to locally simulate a production cluster.

- See [Clustering with DDEV](clustering_with_ddev.md) to add Elasticsearch, Solr, Redis, or Memcached to your DDEV installation.
- See [Clustering with DDEV](clustering_with_ddev.md) to add Elasticsearch, Solr, or Redis to your DDEV installation.
- See [DDEV and Ibexa Cloud](ddev_and_ibexa_cloud.md) to locally run an [[= product_name =]] project by using DDEV.

## Stop or remove the project
Expand Down
22 changes: 9 additions & 13 deletions docs/getting_started/requirements.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ The following server requirements cover both running the software on-premise and
For running on [[[= product_name_cloud =]]](https://www.ibexa.co/products/ibexa-cloud), where recommended configuration and support is provided out of the box, see separate [[[= product_name_cloud =]] section](#ibexa-cloud-requirements-and-setup) for further reading on its requirements.

The minimal setup requires PHP, MySQL/MariaDB, Apache/Nginx, Node.js and `yarn`.
Recommendation for production setups is to use Varnish/Fastly, Redis/Memcached, NFS/EFS/S3 and Solr/Elasticsearch in a [clustered setup](clustering.md).
For production setups it's recommended that you use Varnish/Fastly, Redis, NFS/EFS/S3 and Solr/Elasticsearch in a [clustered setup](clustering.md).

!!! caution "Recommended versions"

Expand All @@ -34,10 +34,7 @@ Recommendation for production setups is to use Varnish/Fastly, Redis/Memcached,

|Name|Version|
|---|---|
|Debian 10 "Buster" |10.0-10.13+|
|Debian 11 "Bullseye"|11.0-11.7+|
|Ubuntu "Focal Fossa" | 20.04 |
|Ubuntu "Jammy Jellyfish"| 22.04 |
|Ubuntu "Noble Numbat"| 24.04 |
|RHEL / CentOS / CentOS Stream | 8.1-9.5+ |

Expand Down Expand Up @@ -75,7 +72,7 @@ Recommendation for production setups is to use Varnish/Fastly, Redis/Memcached,

=== "[[= product_name =]] v5.0"

- Nginx 1.18-1.25+
- Nginx 1.27+
- Apache 2.4 (with required modules `mod_rewrite`, `mod_env` and recommended: `mod_setenvif`, `mod_expires`;
event MPM is recommended, if you need to use prefork you also need the `mod_php` module)

Expand All @@ -101,8 +98,8 @@ Recommendation for production setups is to use Varnish/Fastly, Redis/Memcached,

=== "[[= product_name =]] v5.0"

- MariaDB 10.3-10.11+
- MySQL 8.0
- MariaDB 10.11+
- MySQL 8.4
- PostgreSQL 14

If you see a "+" next to the product version, it indicates a recommended version or higher within the same major release.
Expand Down Expand Up @@ -158,7 +155,6 @@ Recommendation for production setups is to use Varnish/Fastly, Redis/Memcached,
- `php-mysql` (`php-mysqlnd`) or `php-pgsql`
- `php-xml`
- `php-mbstring`
- `php-json`
- `php-process` (on RHEL/CentOS)
- `php-intl`
- `php-curl`
Expand Down Expand Up @@ -202,7 +198,7 @@ Recommendation for production setups is to use Varnish/Fastly, Redis/Memcached,

=== "[[= product_name =]] v5.0"

- `php-redis` or `php-memcached`
- `php-redis`

=== "[[= product_name =]] v4.6"

Expand All @@ -216,7 +212,7 @@ Recommendation for production setups is to use Varnish/Fastly, Redis/Memcached,

=== "[[= product_name =]] v5.0"

- For content search, Solr 7.7 LTS or Solr 8, recommended 8.11.1 or higher.
- For content search, Solr 8.11.1 or higher.
Alternatively, Elasticsearch 7.16.2 or higher 7.x version.
- The above solutions require Oracle Java/Open JDK. The minimum requirement is 8 LTS, recommended 11 LTS.
Newer versions aren't supported.
Expand Down Expand Up @@ -287,7 +283,7 @@ Recommendation for production setups is to use Varnish/Fastly, Redis/Memcached,
=== "[[= product_name =]] v5.0"

- Linux NFS or S3/EFS (for IO, aka binary files stored in content repository, not supported with legacy)
- Redis 4.0+ or 5.0+ (separate instances for session and cache, both using a `volatile-*` [eviction policy](https://redis.io/docs/latest/develop/reference/eviction/), session instance configured for persistence) or [Memcached](https://memcached.org/) 1.5 or higher
- Redis 7.2+ (separate instances for session and cache, both using a `volatile-*` [eviction policy](https://redis.io/docs/latest/develop/reference/eviction/), session instance configured for persistence)
- [Varnish](http://varnish-cache.org/) 6.0LTS or 7.1 with [varnish-modules](https://github.com/varnish/varnish-modules/blob/master/README.md) or [Fastly](https://www.fastly.com/) using [the provided bundle](http_cache.md) (for HTTP Cache)

If you see a "+" next to the product version, it indicates a recommended version or higher within the same major release.
Expand Down Expand Up @@ -329,7 +325,7 @@ Recommendation for production setups is to use Varnish/Fastly, Redis/Memcached,

=== "[[= product_name =]] v5.0"

- Composer: recent 2.7 version
- Composer: recent 2.8 version

=== "[[= product_name =]] v4.6"

Expand All @@ -343,7 +339,7 @@ Recommendation for production setups is to use Varnish/Fastly, Redis/Memcached,

=== "[[= product_name =]] v5.0"

- `Node.js` 18+
- `Node.js` 22+
- `yarn` 1.15.2+

If you see a "+" next to the product version, it indicates a recommended version or higher within the same major release.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -452,7 +452,7 @@ The output for this command should look similar to this:

```
HTTP/1.1 200 OK
Server: nginx/1.20.0
Server: nginx/1.27.0
Content-Type: application/vnd.fos.user-context-hash
Transfer-Encoding: chunked
Connection: keep-alive
Expand Down Expand Up @@ -480,7 +480,7 @@ The output :

```
HTTP/1.1 200 OK
Server: nginx/1.20.0
Server: nginx/1.27.0
Content-Type: text/html; charset=UTF-8
Transfer-Encoding: chunked
Connection: keep-alive
Expand Down Expand Up @@ -533,7 +533,7 @@ The output is:

```
HTTP/1.1 200 OK
Server: nginx/1.20.0
Server: nginx/1.27.0
Content-Type: text/html; charset=UTF-8
Transfer-Encoding: chunked
Connection: keep-alive
Expand Down Expand Up @@ -561,7 +561,7 @@ Output:

```
HTTP/1.1 200 OK
Server: nginx/1.20.0
Server: nginx/1.27.0
Content-Type: text/html; charset=UTF-8
Transfer-Encoding: chunked
Connection: keep-alive
Expand Down
80 changes: 5 additions & 75 deletions docs/infrastructure_and_maintenance/cache/persistence_cache.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ Persistence cache can best be described as an implementation of `SPI\Persistence

As shown in the illustration, this is done in the exact same way as the event layer is a custom implementation of `API\Repository` decorating the main repository.
In the case of persistence cache, instead of sending events on calls passed on to the decorated implementation, most of the load calls are cached, and calls that perform changes purge the affected caches.
Cache handlers *(for example, Memcached, Redis, or Filesystem)* can be configured using Symfony configuration.
Cache handlers *(for example, Redis, or Filesystem)* can be configured using Symfony configuration.
For details on how to reuse this Cache service in your own custom code, see below.

## Transparent cache
Expand Down Expand Up @@ -47,10 +47,10 @@ To see where and how to contribute additional caches, refer to the [source code]
!!! note

Current implementation uses Symfony cache.
It technically supports the following cache backends: [APCu, Array, Chain, Doctrine, Filesystem, Memcached, PDO & Doctrine DBAL, Php Array, Proxy, Redis]([[= symfony_doc =]]/components/cache/cache_pools.html#creating-cache-pools).
[[= product_name =]] officially supports only using Filesystem for single server and Redis or Memcached for clustered setups.
It technically supports the following cache backends: [APCu, Array, Chain, Doctrine, Filesystem, PDO & Doctrine DBAL, Php Array, Proxy, Redis]([[= symfony_doc =]]/components/cache/cache_pools.html#creating-cache-pools).
[[= product_name =]] officially supports only using Filesystem for single server and Redis for clustered setups.

Use of Memcached or Redis as shared cache back end is a requirement for use in clustering setup.
Use of Redis as shared cache back end is a requirement for use in clustering setup.
For an overview of this feature, see [Clustering](clustering.md).
Filesystem adapters, for example, are **not** intended to be used over a shared filesystem.

Expand Down Expand Up @@ -210,79 +210,9 @@ Several cloud providers have managed services that are easier to set up, handle
If you use Platform.sh Enterprise you can benefit from the Redis Sentinel across three nodes for great fault tolerance.
Platform.sh Professional and lower versions offer Redis in single instance mode only.

### Memcached

[Memcached, a distributed caching solution](http://memcached.org/) is a cache solution that is supported for clustering use, as an alternative to Redis.

See [Memcached Cache Adapter in Symfony documentation]([[= symfony_doc =]]/components/cache/adapters/memcached_adapter.html#configure-the-connection) for information on how to configure Memcached.


#### Supported Adapters

There is one Memcached adapter available out of the box.

##### `Symfony\Component\Cache\Adapter\MemcachedAdapter`

**Pros**: Memcached is able to handle much more concurrent load by design (multi threaded), and typically uses far less memory than Redis in general due to a simpler data structure.

**Cons**: 1.5-2x more lookups to the back-end cache server then `RedisTagAwareAdapter`.
Depending on the number of lookups and latency to cache server this might affect page load time.

#### Adjusting configuration

Out of the box in `config/packages/cache_pool/cache.memcached.yaml` you can find a default example that can be used.

!!! note "[[= product_name_cloud =]]"

For [[= product_name_cloud =]]/Platform.sh: This is automatically configured in `vendor/ibexa/core/src/bundle/Core/DependencyInjection/IbexaCoreExtension.php` if you have enabled Memcached as `cache` Platform.sh service.

For anything else, you can enable it with environment variables detected automatically by `vendor/ibexa/core/src/bundle/Core/DependencyInjection/IbexaCoreExtension.php`.
For instance, if you set the following environment variables `export CACHE_POOL="cache.memcached" CACHE_DSN="user:pass@localhost?weight=33"`, it results in config like this:

``` yaml
services:
cache.memcached:
parent: cache.adapter.memcached
tags:
- name: cache.pool
clearer: cache.app_clearer
provider: 'memcached://user:pass@localhost?weight=33'
# Default CACHE_NAMESPACE value, see bin/config/cache_pool/cache.redis.yaml for usage with e.g. multi repo.
namespace: 'ez'
```

See `config/default_parameters.yaml` and `config/cache_pool/cache.memcached.yaml` for further details on `CACHE_POOL`, `CACHE_DSN` and `CACHE_NAMESPACE`.

!!! caution "Clearing Memcached cache"

The regular `php bin/console cache:clear` command doesn't clear Memcached persistence cache.
Use a dedicated Symfony command to clear the pool you have configured: `php bin/console cache:pool:clear cache.memcached`.


!!! caution "Connection errors issue"

If Memcached does display connection errors when using the default (ascii) protocol, then switching to binary protocol *(in the configuration and Memcached daemon)* should resolve the issue.

!!! note

Memcached must not be bound to the local address if clusters are in use, or user logins fail.
To avoid this, in `/etc/memcached.conf` take a look under `# Specify which IP address to listen on. The default is to listen on all IP addresses`

For development environments, change the address below this comment in `/etc/memcached.conf` to `-l 0.0.0.0`

For production environments, follow this more secure instruction from the Memcached man:

> -l <addr>

> Listen on <addr>; default to INADDR\_ANY. <addr> may be specified as host:port.
If you don't specify a port number, the value you specified with -p or -U is used.
You may specify multiple addresses separated by comma or by using -l multiple times.
This is an important option to consider as there is no other way to secure the installation.
Binding to an internal or firewalled network interface is suggested.

## Using cache service

Using the internal cache service allows you to use an interface and without caring whether the system is configured to place the cache in Memcached or on File system.
Using the internal cache service allows you to use an interface and without caring whether the system is configured to place the cache on File system.
And as [[= product_name =]] requires that instances use a cluster-aware cache in cluster setup, you can safely assume your cache is shared *(and invalidated)* across all web servers.

!!! note
Expand Down
9 changes: 4 additions & 5 deletions docs/infrastructure_and_maintenance/clustering/clustering.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,12 +13,12 @@

![Server setup for clustering](server_setup.png)

The number of web servers, Memcached/Redis, Solr, Varnish, Database, and NFS servers, but also whether some servers play several of these roles (typically running Memcached/Redis across the web server), is up to you and your performance needs.
The number of web servers, Redis, Solr, Varnish, Database, and NFS servers, but also whether some servers play several of these roles (typically running Redis across the web server), is up to you and your performance needs.

The minimal requirements are:

- [Shared HTTP cache (using Varnish)](reverse_proxy.md#using-varnish-or-fastly)
- [Shared persistence cache](#shared-persistence-cache) and [sessions](#shared-sessions) (using Redis or Memcached)
- [Shared persistence cache](#shared-persistence-cache) and [sessions](#shared-sessions) (using Redis)
- Shared database (using MySQL/MariaDB)
- [Shared binary files](#shared-binary-files) (using NFS, or S3)

Expand All @@ -35,21 +35,20 @@
### Shared persistence cache

Redis is the recommended cache solution for clustering.
An alternative solution is using Memcached.

See [persistence cache documentation](persistence_cache.md#persistence-cache-configuration) on information on how to configure them.

### Shared sessions

For a [cluster](clustering.md) setup you need to configure sessions to use a back end that is shared between web servers.
The main options out of the box in Symfony are the native PHP Memcached or PHP Redis session handlers, alternatively there is Symfony session handler for PDO (database).
The main option out of the box in Symfony is the PHP Redis session handler, alternatively there is Symfony session handler for PDO (database).

To avoid concurrent access to session data from front-end nodes, if possible you should either:

- Enable [Session locking](https://www.php.net/manual/en/features.session.security.management.php#features.session.security.management.session-locking)
- Use "Sticky Session", aka [Load Balancer Persistence](https://en.wikipedia.org/wiki/Load_balancing_%28computing%29#Persistence)

Session locking is available with `php-memcached`, and with `php-redis` (v4.2.0 and higher).
Session locking is available with `php-redis` (v4.2.0 and higher).

Check failure on line 51 in docs/infrastructure_and_maintenance/clustering/clustering.md

View workflow job for this annotation

GitHub Actions / vale

[vale] docs/infrastructure_and_maintenance/clustering/clustering.md#L51

[Ibexa.VariablesVersion] Use global variable '[[= latest_tag_4_2 =]]' instead of 'v4.2.0'
Raw output
{"message": "[Ibexa.VariablesVersion] Use global variable '[[= latest_tag_4_2 =]]' instead of 'v4.2.0'", "location": {"path": "docs/infrastructure_and_maintenance/clustering/clustering.md", "range": {"start": {"line": 51, "column": 48}}}, "severity": "ERROR"}

On [[= product_name_cloud =]] (and Platform.sh) Redis is preferred and supported.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -120,37 +120,3 @@ You can now check whether Redis works.
For example, the `ddev redis-cli MONITOR` command returns outputs, for example, `"SETEX" "ezp:`, `"MGET" "ezp:`, `"SETEX" "PHPREDIS_SESSION:`, or `"GET" "PHPREDIS_SESSION:`, while navigating into the website, in particular the back office.

See [Redis commands](https://redis.io/docs/latest/commands/) for more details such as information about the [`MONITOR`](https://redis.io/docs/latest/commands/monitor/) command used in the previous example.

### Install Memcached

First, if not already there, append the following [new service](https://doc.ibexa.co/en/latest/infrastructure_and_maintenance/sessions/#handling-sessions-with-memcached) to `config/services.yaml`:

```yaml
app.session.handler.native_memcached:
class: Ibexa\Bundle\Core\Session\Handler\NativeSessionHandler
arguments:
- '%session.save_path%'
- memcached
```

Second, install and set up the add-on.
The following sequence of commands:

1. Adds the Memcached container.
1. Sets Memcached as the cache pool.
1. Sets Memcached as the session handler.
1. Restarts the DDEV cluster and clears application cache.

```bash
ddev add-on get ddev/ddev-memcached
ddev config --web-environment-add CACHE_POOL=cache.memcached
ddev config --web-environment-add CACHE_DSN=memcached
ddev config --web-environment-add SESSION_HANDLER_ID=app.session.handler.native_memcached
ddev config --web-environment-add SESSION_SAVE_PATH=memcached:11211
ddev restart
ddev php bin/console cache:clear
```

You can now check whether everything went right.

For example, the `watch 'ddev exec netcat -w1 memcached 11211 <<< "stats" | grep "cmd_.et "'` command checks whether the `web` service can access the `memcached` service, and displays the increase of `cmd_get` and `cmd_set` while navigating into the website.
Loading
Loading