Setting Up Deployment

The instructions below use make commands. However, make is not always available in a production/build environments. If it is not, you can move the actual commands from the Makefile into your own scripts and execute them instead.

The First Deployment

For any deployment method, when performing the first deployment, it is wise to deploy and prepare the index first, then enable Lightna rendering once the index is ready.

It's important to change the mode to production on the server for proper security, edit env.php and set 'mode' => 'prod'.

Simple Deployment

For simple projects without a pipeline or a build stage, the following steps are sufficient:

1. Enable maintenance mode in env.php and apply changes using ./cli config.apply.
2. Pull the latest changes.
3. Update Composer and Node dependencies as defined in the lock files by running make install.
4. Create a new build by running make build.
5. Make sure the schema is updated by running: make schema.update
6. When needed, invalidate the index or perform a full reindex accordingly: ./cli index.entity.invalidate or ./cli index.update.all
7. Disable maintenance mode.

Seamless Deployments

In the context of Lightna, seamless deployment ensures that changes to the index do not break the website. This applies to cases such as:

• New data added to the index but not yet available.
• The data structure in the index was refactored and is not immediately compatible with the frontend.
• A sensitive index configuration was changed.
• Other similar scenarios.

Starting from here, we consider that the project has a pipeline setup and a build stage.

Preconditions

• Index storages are shared between nodes.
• The edition directory in Lightna is shared across all nodes.
• The following folders are delivered from the build environment to the server:
  • compiler_dir – Contains the compiled build, configured in config.php
  • asset_dir – Contains compiled assets, configured in config.php
• If Opcache is used in write (default) mode, make sure storage.opcache.options.dir is writable for the indexer.

Seamless Backward-Compatible Deployment

A backward-compatible deployment means that the development team acknowledges the asynchronous nature of the index and takes responsibility for delivering changes seamlessly.

While this method allows for the possibility of mistakes due to human error or extra conditions in the code that make it less clean, or more deployments, it is nevertheless widely used, especially in complex projects with large databases. You can find detailed guidance and recommendations on the internet under the topic: Ensuring Backward Compatibility in Distributed Systems.

In addition to your existing deployment, you need to add the following:

• During the build stage, ensure that make install && make build are completed and that compiler_dir and asset_dir are delivered to the server.
• Once the latest changes are deployed to the server, apply the configuration using ./cli config.apply.
• Ensure the schema is up to date by running make schema.update.
• When needed, invalidate the index or perform a full reindex accordingly: ./cli index.entity.invalidate or ./cli index.update.all

Seamless Deployment with Rotating the Index

This approach helps mitigate extra development routines related to backward-compatible deployment. The main idea is to create a new version of the index while keeping the server using the previous version until the new code is deployed.

In addition to a backward-compatible deployment, you need to add the following steps:

• Before rolling out the code, pause the indexer queue processing: ./cli index.queue.block.
• Instruct Lightna to use the current production index version until the new build arrives: ./cli index.version.bind
• Create the next version of the index by executing the command on the new build with access to production index storages: ./cli index.update.all --next-version
• Roll out the code to all nodes. Once a node is updated with the new build, it will start using the next version of the index automatically.
• After the code rollout is completed on all nodes, explicitly switch to the new index version: ./cli index.version.up
• Resume indexer queue processing: ./cli index.queue.unblock
• Clean up the old index version: ./cli index.gc

As you might notice, this method requires double the amount of memory for index storage.