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

* Production environment, which supports all admin features but does not allow you to modify Bitrix components. There is no admin panel in the production environment.

  Use the production environment for a highly available, fault-tolerant Bitrix installation.

  To deploy the production environment, you need to prepare your custom images by adding the relevant Bitrix files to the provided base images.

  You can only deploy the production environment using a Helm chart.

{% note info %}

The admin and production environments share these assets:

* MySQL® database
* Object Storage bucket

{% endnote %}

## Getting started {#before-you-begin}

1. If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../../cli/quickstart.md#install).

   The folder used by default is the one specified when [creating](../../../cli/operations/profile/profile-create.md) 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.

1. In the Managed Service for Kubernetes cluster, create new [namespaces](../../concepts/index.md#namespace) for the admin and production environments, e.g., `bitrix-admin` and `bitrix-prod`.
1. If you want to issue a Let's Encrypt certificate for a Bitrix website using [cert-manager](https://cert-manager.io/), follow [this guide](cert-manager-cloud-dns.md) to install cert-manager with the Yandex Cloud DNS ACME webhook plugin.
1. If you want to use your own certificate for the Bitrix website, create a `Secret` resource in both environments’ namespaces as follows:

    ```yaml
    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>
    ```

1. [Install the csi-s3 application](csi-s3.md). This is a requirement, because Object Storage is used to store shared data.
1. [Create a bucket](../../../storage/operations/buckets/create.md) to house the shared project directories, `upload` and `backup`.
1. [Create a service account](../../../iam/operations/sa/create.md) with the `storage.editor` [role](../../../iam/concepts/access-control/roles.md) for the folder where your bucket is located.
1. [Create a static access key](../../../iam/operations/authentication/manage-access-keys.md) for the service account and save its ID and secret key.
1. [Create a Managed Service for MySQL®](../../../managed-mysql/operations/cluster-create.md) 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`

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

    ```shell
    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.

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

   1. Create a container registry:

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

   1. Configure a [Docker credential helper](../../../container-registry/operations/authentication.md#cred-helper). It enables you to use private Yandex Cloud registries without running the `docker login` command.

      To configure a credential helper, run this command:

      ```bash
      yc container registry configure-docker
      ```

1. [Make sure](../connect/security-groups.md) the security groups for the Managed Service for Kubernetes cluster and its node groups are configured correctly. If a rule is missing, [add it](../../../vpc/operations/security-group-add-rule.md).

    {% note warning %}
    
    The configuration of security groups determines performance and availability of the cluster and the services and applications running in it.
    
    {% endnote %}

## Installation from Cloud Marketplace {#marketplace-install}

1. In the [management console](https://console.yandex.cloud), select a folder.
1. Navigate to **Managed Service for&nbsp;Kubernetes**.
1. Click the name of the [Managed Service for Kubernetes cluster](../../concepts/index.md#kubernetes-cluster) you need and select the ![image](../../../_assets/console-icons/shopping-cart.svg) **Marketplace** tab.
1. Under **Application available for installation**, select [Bitrix](https://yandex.cloud/en/marketplace/products/yc/bitrix-env) and click **Go to install**.
1. Configure the application:
   * **Namespace**: Select the namespace you created earlier for admin environment.
   * **Application name**: Specify the application name.
   * **Volume size**: Specify the [volume](../../concepts/volume.md) 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](https://v1-22.docs.kubernetes.io/docs/reference/generated/kubernetes-api/v1.22/#servicespec-v1-core).
   * **Use certmanager**: Enable to automatically get a Let's Encrypt certificate.

     To successfully get a certificate, [register a public domain zone](../../../dns/operations/zone-create-public.md) 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 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](#before-you-begin).
   * **S3 bucket**: Specify the name of the Object Storage bucket you [created previously](#before-you-begin).
   * **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® MySQL cluster you [created previously](#before-you-begin).
   * **PHP version**: Specify the PHP version for Bitrix. Available versions: `8.2.30`, `8.3.30`, and `8.4.19`.
   * **Use bitrixsetup.php**: Select to install Bitrix from scratch.
   * **Use restore.php**: Select to restore Bitrix from a backup.

1. Click **Install**.
1. Wait for the application to change its status to `Deployed`.
1. Open your project in the browser at the domain name specified in the settings and install Bitrix using the installation wizard.
1. Check your [tools for working with Git repositories](#working-with-git).

## Installation using a Helm chart {#helm-install}

1. [Install Helm](https://helm.sh/docs/intro/install/) v3.8.0 or higher.
1. [Install kubect](https://kubernetes.io/docs/tasks/tools/install-kubectl) and [configure it to work with the new cluster](../connect/index.md#kubectl-connect).
1. To install a [Helm chart](https://helm.sh/docs/topics/charts/) with the Bitrix admin environment, run this command:

   ```bash
   helm pull oci://cr.yandex/yc-marketplace/yandex-cloud/bitrix-env/chart/bitrix-env \
     --version 1.0.6 \
     --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-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 info %}
   
   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](https://opencontainers.org/) (OCI) support in the Helm client.
   
   {% endnote %}

1. To install a [Helm chart](https://helm.sh/docs/topics/charts/) 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:

       ```shell
       git clone <repository_SSH_URL> bitrix
       ```

   1. Prepare the image of your Bitrix PHP app:

      1. Pull the `bitrix-admin-php` image:

         ```shell
         docker pull cr.yandex/yc-marketplace/yandex-cloud/bitrix-env/bitrix/bitrix-admin-php1775660129087745327177484940704164668665505295409:<PHP_version>
         ```

         The possible PHP version values are `8.2.30`, `8.3.30`, and `8.4.19`.

      1. Tag the registry you [created earlier](#before-you-begin):

         ```shell
         docker tag cr.yandex/yc-marketplace/yandex-cloud/bitrix-env/bitrix/bitrix-admin-php1775660129087745327177484940704164668665505295409:<PHP_version> cr.yandex/<registry_ID>/bitrix-env/bitrix/bitrix-admin-php
         ```

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

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

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

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

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

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

   1. 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-nginx1775660129087745327177484940704164668665505295409:1.28.3-v1`.

   1. Run Helm chart installation:

       ```bash
       helm pull oci://cr.yandex/yc-marketplace/yandex-cloud/bitrix-env/chart/bitrix-env \
         --version 1.0.6 \
         --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 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 info %}
       
       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](https://opencontainers.org/) (OCI) support in the Helm client.
       
       {% endnote %}

## Working with a Git repository {#working-with-git}

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

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

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

1. 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:

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

## See also {#see-also}

* [1C Bitrix: Web environment](https://dev.1c-bitrix.ru/learning/course/index.php?COURSE_ID=32&LESSON_ID=29234&LESSON_PATH=3903.4862.29228.29234)
* [Container environment for Bitrix](https://github.com/bitrix-tools/env-docker)