Самостійне розгортання трекера бюджету: відкритий код, Docker і Postgres

Docker Compose не може обробити поточну конфігурацію, доки ви не виберете режим автентифікації. Щоб запустити локальну версію без входу, режим потрібно вказати явно:

AUTH_MODE=none make up

Ця невелика деталь багато говорить про самостійне розгортання програм для обліку особистих фінансів. Запустити контейнери легко. Справжня робота — вирішити, хто матиме до них доступ, де зберігати резервні копії та які сервіси, що підключаються за бажанням, можуть отримувати фінансові дані.

Expense Budget Tracker — трекер бюджету з відкритим кодом за ліцензією MIT, побудований на Next.js і Postgres. Цей посібник описує репозиторій у його нинішньому стані: локальний запуск у Docker для одного технічно підготовленого користувача, задокументований продакшн-варіант на AWS/CDK та окремі керовані кінцеві точки для вебінтерфейсу, MCP і Agent API.

Спершу визначте потрібні вам межі контролю

«Самостійне розгортання» може означати кілька дуже різних конфігурацій. Не варто вважати їх взаємозамінними.

Варіант	Де зберігаються фінансові дані	За що відповідаєте ви	Для кого підходить
Локальний Docker Compose	Postgres у томі Docker на вашому комп'ютері	Контейнери, оновлення, локальний доступ і резервні копії	Один технічно підготовлений користувач, якому вебінтерфейс потрібен переважно на одному комп'ютері
Ваш обліковий запис AWS із задокументованим стеком CDK	RDS і сервіси застосунку у вашому обліковому записі AWS	AWS, Cloudflare, домени, сертифікати, доставлення листів, секрети, моніторинг і резервні копії	Публічне або багатокористувацьке розгортання, якщо ви готові взяти на себе роботу з інфраструктурою
Керований вебзастосунок	Середовище Expense Budget Tracker у керованому сервісі	Ваш обліковий запис і процес внесення даних	Користувач, якому потрібен вебінтерфейс без обслуговування серверів
MCP-конектор керованого сервісу	Робочий простір у керованому сервісі, доступний через MCP	Згода на доступ через OAuth і підключення клієнта	Агент із підтримкою MCP, якому потрібен обмежений доступ на читання або запис
Agent API керованого сервісу	Робочий простір у керованому сервісі, доступний через API	Довготривалий ApiKey, вибір робочого простору й перевірені SQL-запити	Скрипти й термінальні агенти, які можуть безпосередньо надсилати HTTP-запити

Локальна команда Compose не створює api.your-domain.com або mcp.your-domain.com. Ці інтерфейси для програмного доступу є частиною архітектури AWS і керованого сервісу. Якщо підключити хмарний клієнт до https://mcp.expense-budget-tracker.com/mcp, він працюватиме з робочим простором у керованому сервісі, а не з контейнером Postgres на вашому ноутбуці.

Отже, перше запитання для будь-якого самостійно розгорнутого трекера бюджету таке: вам потрібен локальний контроль над вебзастосунком і базою даних чи віддалені інтеграції, для яких необхідне масштабніше розгортання?

Запустіть трекер витрат локально в Docker

Вам знадобляться Git, Docker і Docker Compose. Клонуйте репозиторій і запустіть стек із його кореневої директорії:

git clone https://github.com/kirill-markin/expense-budget-tracker.git
cd expense-budget-tracker
AUTH_MODE=none make up

Потім відкрийте http://localhost:3000.

AUTH_MODE — обов'язкова змінна Compose. Якщо ви не скопіювали .env.example у .env, додавайте цей префікс перед кожною командою Compose. Саме тому він є в усіх командах нижче.

make up — це короткий псевдонім для:

AUTH_MODE=none docker compose -f infra/docker/compose.yml up -d

Поточний файл Compose визначає Postgres 18, сервіс міграцій, який виконується один раз, вебзастосунок на Next.js, сервіс автентифікації та воркер валютних курсів. З AUTH_MODE=none вебзастосунок використовує локального користувача замість входу через Cognito. Сприймайте цей режим як доступ для локальної розробки, а не як автентифікацію для публічного сервера.

Стан контейнерів і журнали застосунку можна переглядати звичайними командами Compose:

AUTH_MODE=none docker compose -f infra/docker/compose.yml ps
AUTH_MODE=none docker compose -f infra/docker/compose.yml logs -f web

Щоб зупинити стек, виконайте:

AUTH_MODE=none make down

У Makefile ця команда запускає docker compose down без -v. Дані Postgres залишаються в іменованому томі pgdata, і стек знову використовує їх під час наступного запуску.

Це зручно, але резервної копії не замінює. Збій хоста, пошкодження диска, випадкове видалення тому або явна команда docker compose down -v усе ще можуть знищити єдину копію.

Не відкривайте цю конфігурацію назовні

Конфігурація Compose публікує вебзастосунок на порту хоста 3000, Postgres — на 5432, а сервіс автентифікації — на 8081. Вона також містить облікові дані бази даних для розробки. Не розміщуйте цю конфігурацію на хості, доступному з інтернету, вважаючи, що Docker автоматично зробив її приватною.

Для встановлення на робочому комп'ютері:

• обмежте мережевий доступ за допомогою брандмауера хоста;
• не перенаправляйте порти 3000, 5432 або 8081 на маршрутизаторі;
• не відкривайте інсталяцію з AUTH_MODE=none через публічний зворотний проксі;
• не зберігайте репозиторій, файли .env і дампи бази даних у загальнодоступних каталогах або сховищах із широким спільним доступом.

У репозиторії задокументовано AWS/CDK як продакшн-варіант розгортання. Однак готової конфігурації з посиленим захистом для кожного VPS, NAS, кластера Kubernetes або домашнього сервера там немає, хоча досвідчений інженер і зможе адаптувати код.

Що працює локально і що зберігається в Postgres

Локальна архітектура достатньо проста, щоб розібратися в ній самостійно:

• Вебзастосунок на Next.js: надає інтерфейси для роботи з бюджетом, транзакціями й балансами, а також панель огляду, деморежим і чат.
• Postgres: зберігає реєстр операцій, бюджетні плани, налаштування робочого простору, метадані рахунків і стан застосунку.
• Контейнер міграцій: застосовує SQL-міграції з репозиторію перед запуском вебсервісу.
• Воркер валютних курсів: отримує загальнодоступні дані про курси й записує їх через роль бази даних з обмеженими правами.
• Сервіс автентифікації: підтримує архітектуру розгортання з автентифікацією; локальний вебзастосунок не використовує Cognito, коли встановлено AUTH_MODE=none.

Postgres — основне джерело даних. Тому це практичний бюджетний застосунок на Postgres для розробників: ви можете перевіряти міграції, розбиратися у зв'язках між таблицями, виконувати запити до власної бази даних і експортувати її стандартними засобами Postgres. Захист на рівні рядків і окремі ролі застосунку залишаються важливими всередині самого застосунку, але не замінюють захисту хоста й резервного копіювання.

Воркер валютних курсів надсилає зовнішні запити, щоб отримати дані про курси. Для цього йому не потрібно передавати рядки вашого реєстру операцій. Додаткові AI-функції мають іншу межу довіри, яку варто розглянути окремо.

Створіть справжню резервну копію, перш ніж вважати дані захищеними

Для стандартної локальної бази даних Compose ця команда створює стиснений архів Postgres на хості:

AUTH_MODE=none docker compose -f infra/docker/compose.yml exec -T postgres \
  pg_dump -U tracker -d tracker --format=custom \
  > expense-budget-tracker.dump

Поводьтеся з цим файлом як із банківською випискою. Він може містити описи транзакцій, баланси, категорії, нотатки та інші дані, за якими вас можна ідентифікувати.

Для дієвого процесу резервного копіювання потрібно ухвалити чотири рішення:

1. Частота: визначте, який обсяг останніх змін ви готові втратити.
2. Друге місце зберігання: скопіюйте дамп за межі хоста Docker, щоб збій одного диска не знищив обидві копії.
3. Шифрування та доступ: захистіть архів під час зберігання й обмежте коло людей, які можуть його читати.
4. Перевірка відновлення: періодично відновлюйте архів в окремому сумісному екземплярі Postgres і перевіряйте транзакції, бюджети та баланси.

Перед оновленням застосунку створіть свіжий дамп. Потім завантажте новий код, перебудуйте образи й знову запустіть стек:

git pull
AUTH_MODE=none make build
AUTH_MODE=none make up

Контейнер міграцій запускається разом зі стеком. Перед оновленням переглядайте зміни у випуску й зберігайте зроблений до оновлення дамп, доки не перевірите застосунок і не виконаєте тестове відновлення.

Самостійне розгортання не означає, що кожен байт автоматично залишається локально

Основний локальний вебінтерфейс і база даних Postgres можуть працювати на вашому комп'ютері. Дані виходять за цю межу, коли ви використовуєте функцію або точку доступу, яка надсилає їх назовні.

Вбудований AI-чат

Вбудований чат використовує OPENAI_API_KEY. Коли ви ним користуєтеся, до OpenAI можуть надходити запити, прикріплений чи видобутий вміст і фінансовий контекст, потрібний для викликів моделі. Поточний шлях запиту встановлює store: false, але провайдер усе одно має його обробити, а інші параметри зберігання даних залежать від налаштувань вашої організації в API. Перегляньте актуальні правила OpenAI щодо даних API, перш ніж надсилати банківські виписки або деталі реєстру операцій.

Трасування Langfuse необов'язкове. Воно вмикається лише тоді, коли разом налаштовано параметри підключення та значення релізу. Коли трасування ввімкнене, трейси чату експортуються до вибраного вами LANGFUSE_BASE_URL. URL Langfuse Cloud додає ще одного зовнішнього обробника даних; самостійно розгорнутий Langfuse переносить цю точку призначення в інфраструктуру, якою керуєте ви.

Якщо ваша вимога звучить як «рядки з фінансовими даними ніколи не надходять до постачальника LLM», не налаштовуйте AI-інтеграцію й не користуйтеся чатом. Якщо ви свідомо ввімкнули звернення до зовнішньої моделі, самостійне розгортання бази даних його не скасовує.

Власне розгортання в AWS

Задокументоване розгортання в AWS розміщує сервіси застосунку та RDS у вашому обліковому записі AWS. Водночас з'являється більше систем і відносин довіри: Cloudflare для DNS та обробки трафіку на периметрі, Cognito для автентифікації, Resend для доставлення листів для входу, сертифікати для публічних доменів, Secrets Manager, моніторинг і додаткові підключення до OpenAI та Langfuse.

Стек CDK містить керовану інфраструктуру резервного копіювання бази даних. Ви й далі вирішуєте, чи відповідає строк зберігання вашим потребам, стежите за збоями, перевіряєте відновлення, оновлюєте секрети, застосовуєте оновлення й реагуєте на інциденти. «Мій обліковий запис AWS» — корисна межа контролю, але вона не означає «без третіх сторін».

Керований вебінтерфейс, MCP і Agent API

Керований вебінтерфейс доступний за адресою app.expense-budget-tracker.com. Цей варіант потребує найменше операційної роботи, але оператор сервісу й хостинг-провайдери стають частиною контуру обробки даних. Прочитайте політику конфіденційності, перш ніж додавати туди реальні фінансові дані.

Клієнт із підтримкою MCP може підключитися до:

https://mcp.expense-budget-tracker.com/mcp

MCP-конектор керованого сервісу використовує браузерну OAuth-авторизацію. Обов'язкова область доступу expenses:read дає змогу переглядати доступні робочі простори та схему, а також виконувати запити на читання. Область expenses:write надається окремо й потрібна для sql_execute. Починайте з доступу лише на читання, якщо клієнту справді не потрібно створювати, змінювати або видаляти фінансові записи. MCP-клієнт також може отримувати дані, які повертають інструменти, тому його політика конфіденційності теж має значення. Повний процес описано в посібнику з MCP-конектора.

Agent API керованого сервісу — це окремий інтерфейс з окремими обліковими даними. Почніть із:

curl --fail --silent --show-error \
  https://api.expense-budget-tracker.com/v1/

Після того як процес початкового підключення з кодом із листа поверне довготривалий ключ, у прямих запитах використовуйте:

Authorization: ApiKey <key>

Основні кінцеві точки SQL навмисно відокремлюють одну операцію читання від однієї схваленої операції запису:

• POST /v1/sql/query приймає один обмежений запит SELECT або WITH ... SELECT.
• POST /v1/sql/execute приймає один схвалений запит INSERT, UPDATE або DELETE.

Вибір робочого простору й захист Postgres на рівні рядків застосовуються на сервері, але не перетворюють звернення до керованого сервісу на звернення до самостійно розгорнутого середовища. Крім того, кінцева точка MCP на основі OAuth не приймає ApiKey. У довіднику API описано виявлення доступних можливостей, вибір робочого простору, перегляд схеми, обмеження запитів і точну політику SQL. У посібнику з API для обліку витрат докладніше пояснено схвалення та звіряння.

Які обов'язки ви берете на себе із самостійним розгортанням

З боку застосунку особисті фінанси для розробників можуть виглядати напрочуд просто: один репозиторій, одна команда Compose, одна база даних. Операційна робота триває і після першого успішного завантаження сторінки.

У разі локального Docker ви відповідаєте за:

• оновлення Docker і операційної системи хоста;
• оновлення застосунку й перевірку міграцій;
• дампи бази даних, зашифровані копії за межами основного хоста, строки зберігання та перевірки відновлення;
• вільне місце на диску й стан контейнерів;
• правила брандмауера й фізичний доступ до комп'ютера;
• захист файлів .env, API-ключів, ключів моделей і резервних копій.

Для публічного розгортання також потрібні:

• домен і конфігурація DNS;
• TLS-сертифікати й процес їх поновлення;
• автентифікований доступ замість AUTH_MODE=none;
• доставлення листів з OTP і відповідні облікові дані;
• моніторинг бази даних і сервісів;
• опрацювання сповіщень, реагування на інциденти та відновлення;
• контроль витрат на хмарні ресурси й захист облікового запису провайдера.

Посібник із самостійного розгортання — це коротка інструкція з налаштування. Підтримувану архітектуру AWS визначає документація з розгортання в репозиторії з вихідним кодом.

Практичний список для ухвалення рішення

Самостійно розгорнутий трекер витрат добре підходить вам, якщо більшість із наведеного описує ваші потреби:

• Ви готові взяти на себе обслуговування Docker і Postgres, а не просто скористатися ними один раз.
• Ви готові автоматизувати резервне копіювання й тестувати відновлення, а не просто покладатися на том.
• Вам потрібен прямий доступ до стандартної бази даних і вихідного коду, який можна перевіряти або змінювати.
• Вам достатньо локального доступу через браузер або ви готові обслуговувати задокументований стек AWS.
• Ви можете не відкривати інсталяцію з AUTH_MODE=none для публічних мереж.
• Ви перевірятимете кожен додатковий шлях передавання даних назовні, особливо AI-чат і телеметрію.

Керований застосунок або інший варіант у керованому сервісі буде доречнішим, якщо вам ближчі такі твердження:

• Ви хочете додавати й переглядати фінансові дані, не займаючись обслуговуванням та оновленням інфраструктури.
• Вам потрібен надійний віддалений доступ, але ви не хочете керувати доменами, TLS, автентифікацією, електронною поштою, секретами й моніторингом.
• Ви навряд чи помітите збій резервного копіювання або запізніле встановлення оновлення безпеки.
• MCP з областями доступу OAuth чи Agent API керованого сервісу можуть задовольнити потребу в інтеграції без обслуговування всього стека.

Є й корисний проміжний варіант: запустити локальну систему без AI-ключів, не відкривати її для публічного інтернету й експортувати зашифровані резервні копії Postgres у сховище під вашим контролем. Так ви отримаєте головну перевагу самостійно розгорнутого трекера бюджету, не видаючи Compose-файл на ноутбуці за продакшн-платформу.

Почніть із AUTH_MODE=none make up, додайте кілька тестових транзакцій без конфіденційних даних, зупиніть і знову запустіть стек, а потім створіть та перевірте дамп бази даних. Якщо цей невеликий операційний цикл здається вам прийнятним, починайте переносити реальні дані. Якщо ж він уже сприймається як зайва морока, керований варіант, імовірно, буде чеснішим вибором.