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.

There are two available environment types:

• Admin environment, where you can:

  • Deploy Bitrix products from scratch or from backups.
  • Modify Bitrix components using the admin panel.
  • Develop and test your products.

  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 set up the environment both from Yandex Cloud Marketplace and using a Helm chart.

  You can use the admin environment to install stable versions of Bitrix applications.

• Product environment, which supports all admin features but does not allow you to modify Bitrix components. There is no admin panel in the product environment.

  You can run multiple Deployment replicas in your product environment, which provides fault tolerance.

  To set up the product environment, you will need to prepare images based on the provided ones by adding the relevant Bitrix files.

  You can only set up the product environment using a Helm chart.

Getting startedGetting started

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

   By default, the CLI uses the folder specified when creating the profile. To change the default folder, use the yc config set folder-id <folder_ID> command. You can also set a different folder for any specific command using the --folder-name or --folder-id parameter.

2. In your Managed Service for Kubernetes cluster, create a new namespace named bitrix-space for the admin environment, and bitrix-prod, for the product environment.

3. 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>
   

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

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

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

7. 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
     • Sync Binlog: 1000
     • Transaction Isolation: read committed

8. 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.

9. If you are going to use the product 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
      

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

    Warning

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

Installation from Cloud MarketplaceInstallation from Cloud Marketplace

1. Navigate to the folder dashboard and select Managed Service for Kubernetes.

2. Click the name of the Managed Service for Kubernetes cluster you need and select the Marketplace tab.

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

4. Configure the application:

   • Namespace: Select the namespace you created earlier.

   • 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: Current 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>-bitrix-space-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 deplyment will start in a separate pod.

   • Store cache in Redis: Enable to store Bitrix cache in Redis. In this case, the cluster will have a separate StatefulSet in the app’s namespace: <app_name>-redis-*. Do not enable this setting in the admin environment as this may lead to degraded performance.

   • 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.

   • Upload directory size: Specify the size for the upload directory in the bucket, in Gi.

   • Backup directory size: Specify the size for the backup directory in the bucket, in Gi.

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

   • MySQL® host, Database user, Database user password, Database: Specify properties for connection to the MySQL® database in the Managed Service for MySQL® cluster you created previously.

   • NGINX version: Select the NGINX version for Bitrix.

   • PHP version: Select the PHP version for Bitrix.

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

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

5. Click Install.

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

7. Open your project in the browser at the domain name specified in the settings and install Bitrix using the installation wizard.

8. 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.

2. Install kubect 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.5 \
     --untar && \
   helm install \
     --namespace bitrix-space \
     --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-json 'mysql={"host":"<MySQL®_host_FQDN>","login":"<MySQL®_user_name>","password":"<MySQL®_user_password>","database":"<MySQL®_database_name>"}' \
     --set certmanager.enabled=false \
     --set tls.existingSecret="<name_of_secret_with_certificate>" \
     --set features.cache=<use_Redis_cache> .
     bitrix ./bitrix/
   

   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, append the export HELM_EXPERIMENTAL_OCI=1 && \ string to the command to enable Open Container Initiative (OCI) support in the Helm client.

4. To install a Helm chart with the Bitrix product environment, do the following:

   1. Create a new namespace in your cluster: bitrix-prod.

   2. Create a local folder named bitrix or, if your project is uploaded to a Git repository, clone your repository to this folder:

      git clone <repository_SSH_URL> bitrix
      

   3. Prepare the image of your Bitrix PHP app:

      1. Download the bitrix-admin-php image:

         docker pull cr.yandex/yc-marketplace/yandex-cloud/bitrix-env/bitrix/bitrix-admin-php1764089856329713384751806090650435327427957097722:8.2.29
         

      2. Tag the registry you created earlier:

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

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

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

      4. Build a Docker image to set up the product environment by running this command:

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

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

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

   4. Repeat step 2 to prepare a Bitrix NGINX image, bitrix-prod-nginx, based on this image: cr.yandex/yc-marketplace/yandex-cloud/bitrix-env/bitrix/bitrix-admin-nginx1764089856329713384751806090650435327427957097722:1.28.

   5. Run Helm chart installation:

      helm pull oci://cr.yandex/yc-marketplace/yandex-cloud/bitrix-env/chart/bitrix-env \
        --version 1.0.5 \
        --untar && \
      helm install \
        --namespace bitrix-prod \
        --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 mysql.host="<MySQL®_host_FQDN>" \
        --set mysql.login="<MySQL®_user_name>" \
        --set mysql.password="<MySQL®_user_password>" \
        --set mysql.database="<MySQL®_database_name>" \
        --set php.image="cr.yandex/<registry_ID>/bitrix-prod-php" \
        --set nginx.image="cr.yandex/<registry_ID>/bitrix-prod-nginx" \
        --set certmanager.enabled=false \
        --set tls.existingSecret="<name_of_secret_with_certificate>" \
        bitrix ./bitrix/
      

      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, append the export HELM_EXPERIMENTAL_OCI=1 && \ string to 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 bitrix-space exec \
     <bitrix_main_pod_name> \
     -c git -it -- \
     sh /home/bitrix/www $
   

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>
   

See alsoSee also

• Container environment for Bitrix
• 1C Bitrix: Site Management
• 1C Bitrix24
• 1C Bitrix: Solutions for industries