Installing Bitrix

Bitrix is an application that prepares and deploys environments for standard installation of 1C Bitrix products in a Yandex Managed Service for Kubernetes cluster.

It supports two environment types: admin and production.

Admin environmentAdmin environment

The admin environment is used for:

• Deployment of Bitrix products from scratch or from a backup.
• Modification of Bitrix components via the admin panel.
• Testing and development.

You can also use this environment to install stable versions of Bitrix applications.

Admin environment supports the following tools:

• Git client.
• Running agents in cron jobs.
• Queue server.
• Sphinx morphological search.
• Tools for collecting PHP and Nginx metrics.

You can install the admin environment from Yandex Cloud Marketplace or using a Helm chart.

Production environmentProduction environment

The production environment is designed for fault-tolerant and highly available Bitrix deployment. It supports all the admin features except for the admin panel and does not allow you to modify Bitrix components.

You can install the production environment only using a Helm chart. Prior to installation, prepare custom images based on those provided and add the necessary Bitrix files to them.

Getting startedGetting started

1. If you do not have the Yandex Cloud CLI yet, install and initialize it.

   The folder used by default is the one specified when creating the CLI profile. To change the default folder, use the yc config set folder-id <folder_ID> command. You can also specify a different folder for any command using --folder-name or --folder-id.

   If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

2. In the Managed Service for Kubernetes cluster, create new namespaces for the admin and production environments, e.g., bitrix-admin and bitrix-prod.

3. If you want to issue a Let's Encrypt certificate for a Bitrix website using cert-manager, follow this guide to install cert-manager with the Yandex Cloud DNS ACME webhook plugin.

4. If you want to use your own certificate for the Bitrix website, create a Secret resource in both environments’ namespaces as follows:

   apiVersion: v1
   kind: Secret
   metadata:
     name: bitrix-tls-secret
     namespace: <namespace>
   type: kubernetes.io/tls
   data:
     tls.crt: <Base64_encoded_certificate>
     tls.key: <Base64_encoded_certificate_private_key>
   

5. Install the csi-s3 application. This is a requirement, because Object Storage is used to store shared data.

6. Create a bucket to house the shared project directories, upload and backup.

7. Create a service account with the storage.editor role for the folder where your bucket is located.

8. Create a static access key for the service account and save its ID and secret key.

9. Create a Managed Service for MySQL® cluster with the following parameters:

   • Network: Select the network hosting your Managed Service for Kubernetes cluster.
   • Under Hosts, check that Public access is disabled for all hosts.
   • DBMS settings:
     • Innodb Flush Log At Trx Commit: 2
     • Innodb Strict Mode: Disabled
     • Join Buffer Size: 2621440
     • Sort Buffer Size: 2621440
     • Sync Binlog: 0
     • Transaction Isolation: read committed

10. If you need to use the queue server (Bitrix Push and Pull module), create a secret key for it:

    docker container run --rm \
        --name push_server_key_generate alpine:3.21 \
        sh -c "(cat /dev/urandom | tr -dc A-Za-z0-9 | head -c 128) && echo ''"
    

    Save the command output.

11. If you are going to use the production environment, prepare Container Registry resources to push the required Docker images:

    1. Create a container registry:

       yc container registry create --name yc-auto-cr
       

    2. Configure a Docker credential helper. It enables you to use private Yandex Cloud registries without running the docker login command.

       To configure a credential helper, run this command:

       yc container registry configure-docker
       

12. Make sure the security groups for the Managed Service for Kubernetes cluster and its node groups are configured correctly. If a rule is missing, add it.

    Warning

    The configuration of security groups determines performance and availability of the cluster and the services and applications running in it.

Installation from Cloud MarketplaceInstallation from Cloud Marketplace

1. In the management console, select the folder.

2. Navigate to Managed Service for Kubernetes.

3. Select the Managed Service for Kubernetes cluster.

4. Click the Other tab and select Marketplace.

5. Under Application available for installation, select Bitrix and click Go to install.

6. Configure the application:

   • Namespace: Select the namespace you created earlier for the admin environment.

   • Application name: Specify the application name.

   • Volume size: Specify the volume size for storing Bitrix files, in Gi.

   • Storage class: Select the storage class for the volume.

   • Project domain name: Specify the full project domain name.

   • Balancer IP address: Specify the balancer IP address if you already reserved one.

   • Traffic management policy: Select a policy for routing external traffic.

   • Use certmanager: Enable to automatically get a Let's Encrypt certificate.

     To successfully get a certificate, register a public domain zone and delegate your domain. A certificate will be issued for the domain in this zone after you pass the DNS-01 challenge.

   • Email address to get notifications from Let's Encrypt: If you enabled Use certmanager, specify the email address for Let's Encrypt® notifications.

   • Issuer name: If you enabled Use certmanager, specify the name of the resource, ClusterIssuer or Issuer, to automatically get SSL or TLS certificates.

   • Secret containing tls.crt and tls.key: If not using certmanager, specify the name of the secret you created previously.

   • Configure Git: Enable if you want to use a Git repo.

     If this is the case, specify the Git repo properties in the relevant fields:

     • Git repository address: Repo address as an SSH URL.
     • Branch: Working branch of your Git repo.
     • User: Git repo user name.
     • Email: Git repo user email.
     • Access key: Specify Base64-encoded contents of the repo access public key.

   • Use cron to run agents: Enable to run Bitrix agents on the schedule specified in ConfigMap <app_name>-<namespace_for_admin_environment>-cron. By default, ConfigMap enables running agent jobs every minute, and backup jobs, every 24 hours. You can also add your own schedule.

   • Use queue server: Enable to use a queue server (the Bitrix Push and Pull module). The Deployment resource for server deployment will start in a separate pod.

   • Secret key: If you enabled Use queue server, provide the secret key you created previously.

   • Use Sphinx: Enable to use Sphinx, a full-text search engine. The Deployment resource for Sphinx deployment will start in a separate pod.

   • Use built-in Redis: Leave this option on to deploy Redis together with the application. In which case the External Redis host and Redis password fields should remain empty.

     For connection to a separately deployed Redis instance, disable this option and specify the following:

     • External Redis host: Specify the address of the server accessible from the application. This is a required setting.
     • External Redis port: Specify the connection port. The default value is 6379.
     • Redis password: Specify the connection password. Leave this field empty if the server requires no password.

     Redis is used to store sessions regardless of the Store cache in Redis option. Disabling the built-in Redis requires a connection to an external one.

   • Store cache in Redis: Enable to store Bitrix cache in Redis. We do not recommend enabling this option in the admin environment.

   • Export PHP metrics: Select to enable PHP metrics.

   • Export NGINX metrics: Select to enable NGINX metrics.

   • Storage class for S3: csi-s3, default.

   • S3 key ID, S3 secret key: Specify the ID and secret key of the static key you got previously.

   • S3 bucket: Specify the name of the Object Storage bucket you created previously.

   • SMTP server, SMTP port, Mailbox user, Mailbox password: Specify the mail server connection properties.

   • PHP version: Specify the PHP version for Bitrix. Available versions: 8.2.33, 8.3.33, 8.4.25, and 8.5.10.

   • Use bitrixsetup.php: Select to install Bitrix from scratch.

   • Use restore.php: Select to restore Bitrix from a backup.

7. Click Install.

8. Wait for the application to change its status to Deployed.

9. Open your project in the browser at the domain name specified in the settings and install Bitrix using the installation wizard. When configuring your database, specify the host address, database name, user login and password in the Managed Service for MySQL® cluster you created earlier.

10. Check your tools for working with Git repositories.

Installation using a Helm chartInstallation using a Helm chart

1. Install Helm v3.8.0 or higher.

   Additional chart settings and available image tags are listed in values.yaml. To print its contents, run this command:

   helm show values oci://cr.yandex/yc-marketplace/yandex-cloud/bitrix-env/chart/bitrix-env \
     --version 1.0.7
   

2. Install kubectl and configure it to work with the new cluster.

3. To install a Helm chart with the Bitrix admin environment, run this command:

   helm pull oci://cr.yandex/yc-marketplace/yandex-cloud/bitrix-env/chart/bitrix-env \
     --version 1.0.7 \
     --untar && \
   helm install \
     --namespace <namespace_for_admin_environment> \
     --set volumeSize="<Bitrix_volume_size>" \
     --set fqdn="<Bitrix_website_domain_name>" \
     --set loadBalancerIP="<load_balancer_IP_address>" \
     --set features.cron=<use_cron_to_run_agents> \
     --set features.push=<use_queue_server> \
     --set features.sphinx=<use_Sphinx_search> \
     --set features.phpExporter=<export_PHP_metrics> \
     --set features.nginxExporter=<export_NGINX_metrics> \
     --set features.git=<use_Git> \
     --set git.repoUrl="<repository_SSH_URL>" \
     --set git.name="<Git_user_name>" \
     --set git.email="<Git_user_email>" \
     --set git.secret="<Base64_acess_key_of_Git_user>" \
     --set s3.secret.accessKey="<bucket_key_ID>" \
     --set s3.secret.secretKey="<bucket_secret_key>" \
     --set s3.bucket="<bucket_name>" \
     --set msmtprc.host="<email_server_FQDN>" \
     --set msmtprc.port="<email_server_port>" \
     --set msmtprc.user="<email_server_user_name>" \
     --set msmtprc.password="<email_server_user_password>" \
     --set push.key="<secret_key_of_Bitrix_Push_server>" \
     --set certmanager.enabled=false \
     --set tls.existingSecret="<name_of_secret_with_certificate>" \
     bitrix ./bitrix-env/
   

   When using certmanager to issue a certificate, instead of the tls.existingSecret and certmanager.enabled=false parameters, specify the following ones:

   • certmanager.issuer=<Issuer_or_ClusterIssuer_resource>
   • certmanager.email=<email_for_Lets_Encrypt_notifications>

   Note

   If you are using a Helm version below 3.8.0, add the export HELM_EXPERIMENTAL_OCI=1 && \ string at the beginning of the command to enable Open Container Initiative (OCI) support in the Helm client.

   After you have deployed the admin environment, open your project at the specified domain name and install Bitrix using the installation wizard. When configuring your database, specify the parameters for connection to the Managed Service for MySQL® cluster created earlier:

4. To install a Helm chart with the Bitrix production environment, proceed as follows:

   1. If your project is uploaded to a Git repository, clone your repository to the bitrix folder:

      git clone <repository_SSH_URL> bitrix
      

   2. Prepare the image of your Bitrix PHP app. Use the same <php_version> tag at every stage: the chart uses it to figure out the path to the PHP configuration. Make sure the tag contains the full version in MAJOR.MINOR.PATCH format, e.g., 8.5.10.

      1. Pull the bitrix-admin-php image:

         docker pull cr.yandex/yc-marketplace/yandex-cloud/bitrix-env/bitrix/bitrix-admin-php1789566872190363361228058870643905000661686010862:<php_version>
         

      2. Tag the registry you created earlier:

         docker tag cr.yandex/yc-marketplace/yandex-cloud/bitrix-env/bitrix/bitrix-admin-php1789566872190363361228058870643905000661686010862:<php_version> cr.yandex/<registry_ID>/bitrix-env/bitrix/bitrix-admin-php:<php_version>
         

      3. In the bitrix folder home directory, create a file named Dockerfile with the following contents:

         FROM cr.yandex/<registry_ID>/bitrix-env/bitrix/bitrix-admin-php:<php_version>
         COPY --chown=bitrix:bitrix bitrix/ /home/bitrix/www
         WORKDIR /home/bitrix/www
         

      4. Build a Docker image to deploy the production environment by running this command:

         docker build --platform linux/amd64 \
             -t cr.yandex/<registry_ID>/bitrix-prod-php:<php_version> \
             --no-cache .
         

      5. Push your new image to the registry by running this command:

         docker push cr.yandex/<registry_ID>/bitrix-prod-php:<php_version>
         

   3. Repeat step 2 to prepare a Bitrix NGINX image, bitrix-prod-nginx, based on this base image: cr.yandex/yc-marketplace/yandex-cloud/bitrix-env/bitrix/bitrix-admin-nginx1789566872190363361228058870643905000661686010862:<nginx_version>.

   4. Prepare the .settings.php file with the installed Bitrix product settings. For example, export it from the php container of the <release_name>-<admin_enrivonment_workspace>-main Deployment pod.

      kubectl exec \
        --namespace <namespace_for_admin_environment> \
        deploy/<release_name>-<namespace_for_admin_environment>-main \
        -c php -- cat /home/bitrix/www/bitrix/.settings.php > settings.php
      

   5. Create a secret named bitrix-user-settings with the .settings.php key in the product environment namespace created earlier:

      kubectl create secret generic bitrix-user-settings \
        --namespace <namespace_for_production_environment> \
        --from-file=.settings.php=./settings.php
      

   6. Run Helm chart installation:

      helm pull oci://cr.yandex/yc-marketplace/yandex-cloud/bitrix-env/chart/bitrix-env \
        --version 1.0.7 \
        --untar && \
      helm install \
        --namespace <namespace_for_production_environment> \
        --set environment=prod \
        --set replicaCount=<number_of_Bitrix_pod_replicas> \
        --set fqdn="<Bitrix_website_domain_name>" \
        --set loadBalancerIP="<load_balancer_IP_address>" \
        --set features.cron=<use_cron_to_run_agents> \
        --set features.push=<use_queue_server> \
        --set features.sphinx=<use_Sphinx_search> \
        --set features.phpExporter=<export_PHP_metrics> \
        --set features.nginxExporter=<export_NGINX_metrics> \
        --set s3.secret.accessKey="<bucket_key_ID>" \
        --set s3.secret.secretKey="<bucket_secret_key>" \
        --set s3.bucket="<bucket_name>" \
        --set msmtprc.host="<email_server_FQDN>" \
        --set msmtprc.port="<email_server_port>" \
        --set msmtprc.user="<email_server_user_name>" \
        --set msmtprc.password="<email_server_user_password>" \
        --set push.key="<secret_key_of_Bitrix_Push_server>" \
        --set settings.existingSecret="bitrix-user-settings" \
        --set php.image="cr.yandex/<registry_ID>/bitrix-prod-php:<php_version>" \
        --set nginx.image="cr.yandex/<registry_ID>/bitrix-prod-nginx:<nginx_version>" \
        --set certmanager.enabled=false \
        --set tls.existingSecret="<name_of_secret_with_certificate>" \
        bitrix ./bitrix-env/
      

      When using certmanager to issue a certificate, instead of the tls.existingSecret and certmanager.enabled=false parameters, specify the following ones:

      • certmanager.issuer="<Issuer_or_ClusterIssuer_resource>"
      • certmanager.email="<email_for_Lets_Encrypt_notifications>"

      Note

      If you are using a Helm version below 3.8.0, add the export HELM_EXPERIMENTAL_OCI=1 && \ string at the beginning of the command to enable Open Container Initiative (OCI) support in the Helm client.

Working with a Git repositoryWorking with a Git repository

To work with a repository, you need the admin environment.

1. Connect to the pod container from the admin environment:

   kubectl -n <namespace_for_admin_environment> exec \
     <bitrix_main_pod_name> \
     -c git -it -- sh
   

2. The container supports git commands, as well as a utility script, /scripts/commit-all.sh, to push all changes from the bitrix directory to the repo you configured in the previous steps. To use it, run this command:

   /scripts/commit-all.sh <commit description>
   

Useful linksUseful links

• 1C Bitrix: Web environment
• Container environment for Bitrix