# Запуск Picodata

В данном разделе приведена информация по запуску отдельного инстанса
Picodata на физическом оборудовании или в виртуальной среде.

[Инстанс](../overview/glossary.md#instance) — экземпляр приложения
Picodata, из которых состоит кластер. Picodata может создать кластер,
состоящий всего из одного экземпляра/инстанса.

## Минимальный вариант запуска {: #simple_run }

В самом простом случае запуск инстанса сводится к выполнению команды
 `picodata run` без каких-либо параметров:

```shell
picodata run
```

Будет запущен кластер, состоящий из одного инстанса. Все параметры будут
стандартны, и, скорее всего, вы захотите их переопределить.

Читайте далее:

- [Конфигурирование](../admin/configure.md)
- [Подключение и работа в консоли](../tutorial/connecting.md)

## Запуск нескольких инстансов {: #run_multiple_instances }

Для того чтобы запустить несколько инстансов на одном сервере,
потребуется задать дополнительные параметры для каждого из них:

- рабочую директорию ([`--instance-dir`])
- сетевой адрес ([`--iproto-listen`])
- адрес одного или нескольких соседних инстансов ([`--peer`])
- адрес сервера PostgreSQL ([`--pg-listen`])

Полный перечень возможных параметров запуска и их
описание содержатся в разделе [Аргументы командной строки], а также в
выводе команды `picodata run --help`.

[Аргументы командной строки]: ../reference/cli.md

Чтобы запустить два инстанса, которые объединятся в кластер,
выполните в двух соседних терминалах следующие команды:

```shell
picodata run --instance-dir ./data/i1 --iproto-listen 127.0.0.1:3301 --pg-listen 127.0.0.1:4327
```

```shell
picodata run --instance-dir ./data/i2 --iproto-listen 127.0.0.1:3302 --pg-listen 127.0.0.1:4328 --peer 127.0.0.1:3301
```

Обратите внимание на различия в запуске инстансов:

- каждый инстанс использует свою рабочую директорию и сетевой адрес
- в отсутствие параметра `--peer` запуск инстанса приводит к созданию
  нового кластера. Чтобы инстансы добавлялись в уже существующий кластер,
  в этом параметре передается адрес первого инстанса

[`--instance-dir`]: ../reference/cli.md#run_instance_dir
[`--iproto-listen`]: ../reference/cli.md#run_iproto_listen
[`--peer`]: ../reference/cli.md#run_peer
[`--pg-listen`]: ../reference/cli.md#run_pg_listen

Читайте далее:

- [Создание кластера](../tutorial/deploy.md)

## Запуск с помощью Docker Compose {: #run_docker_compose }

Picodata поддерживает запуск при помощи инструментария Docker Compose и
предоставляет пример файла `docker-compose.yml` для запуска тестового
кластера. Этот способ удобен тем, что позволяет запускать Picodata без
необходимости [установки пакетов][available_packages] или [сборки из
исходного кода][installing_from_sources].

[available_packages]: install.md#available_packages
[installing_from_sources]: install.md#installing_from_sources

Для развёртывания тестового кластера данным способом выполните следующие шаги.

Убедитесь, что у вас установлены Docker, Docker Compose, а также что
системная служба `docker` запущена, см [Docker Compose
overview](https://docs.docker.com/compose/)

Скачайте файл [docker-compose.yml], который описывает тестовый кластер
из 4-х инстансов:

[docker-compose.yml]: https://git.picodata.io/core/picodata/-/raw/master/docker/docker-compose.yml?inline=false

```bash
curl -O https://git.picodata.io/core/picodata/-/raw/master/docker/docker-compose.yml
```

Создайте директорию для рабочих файлов проекта и
задайте путь к Docker-репозиторию Picodata:

```shell
mkdir pico
export REGISTRY=docker-public.binary.picodata.io
```

Запустите контейнеры:

```shell
docker-compose up -d
```

Подключиться к кластеру можно одним из следующих способов.

Для подключения к [консоли администратора](../tutorial/connecting.md#admin_console)
используйте команду:

```shell
picodata admin pico/data/picodata-1-1/admin.sock
```

Для подключения к пользовательской консоли по протоколу
[PostgreSQL](../tutorial/connecting.md#postgresql) используйте команду:

```shell
psql postgres://admin@127.0.0.1:4327
```

Пароль администратора `T0psecret` задан через
переменную окружения `PICODATA_ADMIN_PASSWORD`, см. [docker-compose.yml:17]

[docker-compose.yml:17]: https://git.picodata.io/core/picodata/-/blob/master/docker/docker-compose.yml#L17

## Безопасный запуск {: #secure_run }

Для обеспечения мер безопасности рекомендуется организовать хранение
пароля для внутреннего системного пользователя `pico_service` в
отдельном файле `.picodata-cookie`, который следует поместить в [рабочую
директорию инстанса]. Пароль пользователя `pico_service` используется в
рамках всего кластера, поэтому его нужно задать одинаковым для всех
инстансов кластера до их первого запуска (соответственно, следует также
заранее подготовить рабочие директории инстансов).

Дополнительно, в опции [`--audit`] явно укажите способ вывода [журнала
аудита](../admin/audit_log.md).

Также рекомендуется использовать опцию [`--shredding`], которая
обеспечивает безопасное удаление рабочих файлов.

Пример команд, реализующих безопасный запуск:

```shell
mkdir data
echo "shAreDs3cr3t" > data/.picodata-cookie
chmod 600 data/.picodata-cookie
picodata run --instance-dir=data --audit audit.log --shredding
```

[`--audit`]: ../reference/cli.md#run_audit
[`--shredding`]: ../reference/cli.md#run_shredding
[рабочую директорию инстанса]: ../reference/cli.md#run_instance_dir

## Завершение работы и обработка сигналов {: #secure_stop }

Способ завершения процесса `picodata` может отличаться в зависимости от
того, как этот процесс был запущен.

Если инстанс Picodata был запущен через Ansible, то процесс инстанса
управляется менеджером Systemd, причем имя службы инстанса формируется
по схеме `<cluster_name>@<instance_name>.service`. Соответственно, для
остановки службы введите команду:

```shell title="Пример для службы `test@default-1000.service`, запущенной администратором хоста"
sudo systemctl stop test@default-1000.service
```

или:

```shell title="Пример для службы `test@default-1000.service`, запущенной от имени обычного пользователя хоста"
systemctl --user stop test@default-1000.service
```

Если инстанс Picodata был запущен локально, но обернут в виде
юнита/службы Systemd, то для остановки инстанса нужно сначала определить
имя службы, которая управляет процессом инстанса. Это тем более важно,
если таким образом на одном хосте выполняется несколько инстансов
Picodata.

Для начала выясните список запущенных процессов Picodata:

```shell
ps -o'pid,args,unit' `pgrep picodata`
```

В колонке `UNIT` будет указано имя службы Systemd, которую можно
остановить через `systemctl stop`. Если имя службы выглядит как
`user@1000.service` (где 1000 — UID пользователя, из-под которого был
запущен процесс), то инстанс был запущен напрямую из консоли, скрипта
или как-либо еще без задействования Systemd. В таком случае для
остановки инстанса нужно послать сигнал завершения его процессу.

Для безопасного завершения процесса `picodata` используйте следующие сигналы:

- **SIGINT**. `kill -2 [pid]`
- **SIGTERM**. `kill -15 [pid]`

Для ротирования файлов журнала процесса `picodata` (прекращения записи в
прежний файл) используйте `SIGHUP`:

- **SIGHUP**. `kill -1 [pid]`

Если инстанс был запущен непосредственно в терминале, с одновременным
выводом в него диагностических сообщений (_stdout_), то достаточно
нажать сочетание клавиш ++ctrl+c++ , что эквивалентно отправке процессу
`SIGINT`. После этого процесс инстанса будет корректно завершен.

См. также:

- [Получение данных о кластере](../admin/local_monitoring.md)
- [Dashboard для Grafana](../admin/grafana_monitoring.md)
