118 lines
4.0 KiB
Markdown
118 lines
4.0 KiB
Markdown
# Contract: Application Binary
|
||
|
||
Version: 1.0
|
||
|
||
## Purpose
|
||
|
||
Правила сборки, упаковки ресурсов и первого запуска Go-приложений.
|
||
|
||
---
|
||
|
||
## Бинарник
|
||
|
||
Бинарник самодостаточен — все ресурсы встроены через `//go:embed`:
|
||
|
||
- HTML-шаблоны
|
||
- Статика (JS, CSS, иконки)
|
||
- Шаблон конфиг-файла (`config.template.yaml`)
|
||
- Миграции БД
|
||
|
||
Никаких внешних папок рядом с бинарником не требуется для запуска.
|
||
|
||
---
|
||
|
||
## Конфиг-файл
|
||
|
||
Создаётся автоматически при первом запуске, если не существует.
|
||
|
||
### Расположение
|
||
|
||
| Режим приложения | Путь |
|
||
|---|---|
|
||
| Однопользовательское | `~/.config/<appname>/config.yaml` |
|
||
| Серверное / многопользовательское | `/etc/<appname>/config.yaml` или рядом с бинарником |
|
||
|
||
Приложение само определяет путь и создаёт директорию если её нет.
|
||
|
||
### Содержимое
|
||
|
||
Конфиг хранит:
|
||
|
||
- Настройки приложения (порт, язык, таймауты, feature flags)
|
||
- Параметры подключения к централизованной СУБД (host, port, user, password, dbname)
|
||
|
||
Конфиг **не хранит**:
|
||
|
||
- Данные пользователя
|
||
- Кеш или состояние
|
||
- Что-либо что относится к SQLite (см. ниже)
|
||
|
||
### Шаблон
|
||
|
||
Шаблон конфига встроен в бинарник. При создании файла шаблон копируется в целевой путь.
|
||
Шаблон содержит все ключи с комментариями и дефолтными значениями.
|
||
|
||
```yaml
|
||
# <appname> configuration
|
||
# Generated on first run. Edit as needed.
|
||
|
||
server:
|
||
port: 8080
|
||
|
||
database:
|
||
host: localhost
|
||
port: 5432
|
||
user: ""
|
||
password: ""
|
||
dbname: ""
|
||
|
||
# ... остальные настройки
|
||
```
|
||
|
||
---
|
||
|
||
## SQLite (однопользовательский режим)
|
||
|
||
Если приложение использует локальную SQLite:
|
||
|
||
- Файл хранится рядом с конфигом: `~/.config/<appname>/<appname>.db`
|
||
- Путь к файлу не выносится в конфиг — приложение вычисляет его из пути конфига
|
||
- SQLite **не хранит** параметры подключения к централизованной СУБД — только локальные данные приложения
|
||
|
||
---
|
||
|
||
## Первый запуск — алгоритм
|
||
|
||
```
|
||
Старт приложения
|
||
│
|
||
├── Конфиг существует? → Нет → создать директорию → скопировать шаблон → сообщить пользователю путь
|
||
│ → завершить с кодом 0
|
||
│ (пользователь заполняет конфиг)
|
||
└── Конфиг существует? → Да → валидировать → запустить приложение
|
||
```
|
||
|
||
При первом создании конфига приложение **не запускается** — выводит сообщение:
|
||
|
||
```
|
||
Config created: ~/.config/<appname>/config.yaml
|
||
Edit the file and restart the application.
|
||
```
|
||
|
||
---
|
||
|
||
## Сборка
|
||
|
||
Финальный бинарник собирается без CGO если это возможно (для SQLite — с CGO):
|
||
|
||
```
|
||
CGO_ENABLED=0 go build -ldflags="-s -w" -o bin/<appname> ./cmd/<appname>
|
||
```
|
||
|
||
С SQLite:
|
||
```
|
||
CGO_ENABLED=1 go build -ldflags="-s -w" -o bin/<appname> ./cmd/<appname>
|
||
```
|
||
|
||
Бинарник не зависит от рабочей директории запуска.
|