Самостійне розгортання на Railway

ChurchApps публікує шаблон Railway для розгортання в один клік, який надає вашій церкві власний приватний екземпляр B1 Admin, порталу учасників B1, API та бази даних MySQL — усе це працює на інфраструктурі, якою ви володієте і за яку платите безпосередньо. Цей посібник допоможе вам запуститися приблизно за 15 хвилин, а потім розгляне налаштування після розгортання, які більшість церков зрештою хоче зробити.

Швидкий старт

1. Натисніть кнопку Deploy on Railway вище.
2. Увійдіть до Railway (або створіть безкоштовний обліковий запис) і додайте спосіб оплати.
3. Натисніть Deploy, нічого не змінюючи — кожна змінна має розумне типове значення.
4. Зачекайте 5–10 хвилин, поки чотири сервіси не позеленіють.
5. Відкрийте URL сервісу B1Admin, натисніть Register і створіть свій обліковий запис. Перший обліковий запис автоматично отримує права адміністратора сервера.
6. Дотримуйтесь підказок у застосунку, щоб створити свою першу церкву.

Ось і все. Тепер у вас є повноцінно працюючий екземпляр ChurchApps. Усе нижче — необов'язкове доопрацювання.

поради

Розгортання наразі перебуває в бета-версії. Якщо ви зіткнетеся з тим, що документація не охоплює, будь ласка, відкрийте issue на github.com/ChurchApps/Api/issues і додайте журнали розгортання.

Що вам знадобиться

• Безкоштовний обліковий запис Railway
• Кредитна картка, прив'язана до Railway (~$15–25/місяць для невеликої громади; див. Витрати)
• Близько 15 хвилин на початкове розгортання
• Необов'язково, але настійно рекомендовано пізніше: облікові дані SMTP і власний домен

Що розгортається

Шаблон створює чотири сервіси в одному проєкті Railway:

Сервіс	Призначення	URL після розгортання
MySQL	Зберігає всі дані (один екземпляр, кілька схем)	лише внутрішній
Api	Бекенд для членства, контенту, пожертв, відвідуваності тощо	https://api-<id>.up.railway.app
B1Admin	Веб-застосунок для персоналу та адміністраторів	https://b1admin-<id>.up.railway.app
B1App	Веб-застосунок для учасників і вебсайт церкви	https://b1app-<id>.up.railway.app

Схеми бази даних створюються автоматично під час першого запуску за допомогою стартової міграції API.

Початкове налаштування

Тепер, коли ваш екземпляр працює, ось що більшість церков налаштовує далі, приблизно в порядку пріоритету.

1. Електронна пошта (настійно рекомендовано)

Без електронної пошти учасники все ще можуть реєструватися та користуватися системою, але вони не можуть скинути забуті паролі — це має зробити за них адміністратор. Налаштування SMTP займає близько 5 хвилин.

На панелі керування Railway відкрийте сервіс Api → Variables і додайте:

MAIL_SYSTEM=SMTP
SMTP_HOST=<хост вашого провайдера>
SMTP_USER=<ваше ім'я користувача>
SMTP_PASS=<ваш пароль або ключ API>
SMTP_SECURE=false
SUPPORT_EMAIL=noreply@yourchurch.org

Варто знати про три провайдери:

Resend — найпростіший безкоштовний варіант (100 листів на день)

1. Зареєструйтеся на resend.com.
2. Підтвердіть домен для надсилання (або використовуйте тестового відправника onboarding@resend.dev, щоб почати).
3. Створіть ключ API.
4. Встановіть SMTP_HOST=smtp.resend.com, SMTP_USER=resend, SMTP_PASS=re_xxxxxxxxx.

Gmail — безкоштовно для особистого використання (~500 на день)

1. Увімкніть двофакторну автентифікацію для облікового запису Google.
2. Створіть пароль застосунку.
3. Встановіть SMTP_HOST=smtp.gmail.com, SMTP_USER=your-address@gmail.com, SMTP_PASS=<16-символьний пароль застосунку>.

AWS SES — найдешевший варіант для великих обсягів

1. Підтвердіть домен для надсилання в AWS.
2. Вийдіть із «пісочниці» SES, якщо плануєте надсилати на непідтверджені адреси.
3. Створіть облікові дані SMTP у розділі SES → SMTP Settings → Create credentials.
4. Встановіть SMTP_HOST=email-smtp.us-east-2.amazonaws.com, SMTP_USER=AKIA..., SMTP_PASS=<пароль SMTP для SES>.

Після збереження змінних сервіс Api автоматично перерозгортається. Перевірте роботу, ініціювавши скидання пароля для тестового облікового запису.

попередження

Якщо ви встановите MAIL_SYSTEM=SMTP з неправильними обліковими даними, реєстрація виглядатиме успішною, але лист із підтвердженням так і не прийде. Або виправте облікові дані, або видаліть MAIL_SYSTEM, щоб повернутися до режиму без електронної пошти.

2. Власні домени

Типові URL *.up.railway.app працюють, але більшість церков хоче мати власні.

Для кожного вебсервісу (B1Admin і B1App):

1. Відкрийте сервіс у Railway → Settings → Networking.
2. Натисніть + Custom Domain і введіть ім'я хоста:
   • admin.yourchurch.org для B1Admin
   • app.yourchurch.org (або www) для B1App
3. Додайте запис CNAME, який показує Railway, до свого DNS-провайдера.
4. Зачекайте кілька хвилин, поки DNS пошириться. Railway автоматично видасть сертифікат TLS.

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

B1ADMIN_ROOT=https://admin.yourchurch.org

А на сервісі B1Admin:

REACT_APP_API_BASE=https://api.yourchurch.org   (якщо ви також встановили власний домен API)
REACT_APP_B1_WEBSITE_URL=https://{subdomain}.yourchurch.org

Токен {subdomain} є буквальним — під час роботи його замінює піддомен кожної церкви (див. Багатосайтовість нижче).

3. Багатосайтовість (кілька церков на одному екземплярі)

ChurchApps за задумом є багатоорендним — одне розгортання може обслуговувати будь-яку кількість церков, кожна з власними людьми, групами та вебсайтом. Нові церкви додаються повністю через адміністративний інтерфейс; жодних змін інфраструктури не потрібно.

Додавання інших церков

1. У B1 Admin перейдіть до Settings → Manage Church → Switch Church → Create New.
2. Кожна церква має унікальний піддомен (наприклад, firstchurch, gracecommunity).
3. Нова церква отримує власні дані, учасників, вебсайт і налаштування пожертв, повністю ізольовані від інших церков на цьому екземплярі.

Маршрутизація кожної церкви на власний URL

Є два способи публічно відкрити церкви:

Шаблон	Приклад	Налаштування
На основі шляху (працює одразу)	app.yourchurch.org/firstchurch	Додаткових налаштувань не потрібно
На основі піддомену (чистіші URL)	firstchurch.yourchurch.org	Wildcard DNS + wildcard власний домен

Для маршрутизації на основі піддомену на Railway:

1. У своєму DNS-провайдері створіть wildcard CNAME: *.yourchurch.org → <ціль Railway для b1app>.
2. У Railway, на сервісі B1App → Settings → Networking, додайте *.yourchurch.org як власний домен.
3. На сервісі B1Admin встановіть REACT_APP_B1_WEBSITE_URL=https://{subdomain}.yourchurch.org.

Після повторного розгортання сайт кожної церкви автоматично доступний за адресою <їхній-піддомен>.yourchurch.org.

інформація

Wildcard-домени потребують платного плану Railway. Маршрутизація на основі шляху працює на кожному плані і функціонально ідентична — просто менш красива в адресному рядку.

4. Онлайн-пожертви (Stripe / PayPal)

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

1. Отримайте облікові дані розробника в Stripe (Developers → API keys) або PayPal (My Apps & Credentials).
2. У B1 Admin перейдіть до Settings → Giving Settings.
3. Виберіть провайдера, вставте публічний і секретний ключі та налаштуйте обробку комісій.
4. За бажанням додайте GOOGLE_RECAPTCHA_SECRET_KEY до сервісу Api у Railway, щоб захистити публічні форми пожертв від ботів.

5. Сховище файлів

Шаблон створює постійний том на 1 ГБ, підключений до сервісу Api, для фотографій учасників, файлів проповідей і завантажених документів.

Щоб збільшити його: відкрийте сервіс Api → Volumes → змініть розмір повзунком.

Для більших розгортань (100+ ГБ або багато одночасних завантажень) перейдіть на S3, встановивши на сервісі Api такі змінні:

FILE_STORE=S3
AWS_S3_BUCKET=<your-bucket>
AWS_ACCESS_KEY_ID=<key>
AWS_SECRET_ACCESS_KEY=<secret>
AWS_REGION=us-east-2

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

6. Додаткові інтеграції функцій

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

Змінна	Функція, яку вона вмикає
OPENAI_API_KEY або OPENROUTER_API_KEY	Пошук і пропозиції контенту за допомогою ШІ
YOUTUBE_API_KEY	Пошук і вбудовування проповідей з YouTube
PEXELS_KEY	Вибір стокових зображень для конструктора вебсайтів
VIMEO_TOKEN	Підтримка проповідей з Vimeo
API_BIBLE_KEY	Пошук віршів Біблії в уроках і контенті
YOUVERSION_API_KEY	Інтеграція з YouVersion Bible
WEB_PUSH_PUBLIC_KEY + WEB_PUSH_PRIVATE_KEY	Push-сповіщення у браузері (згенерувати пару ключів VAPID)
HUBSPOT_KEY	Необов'язкова синхронізація з CRM для нових реєстрацій

Оновлення

Кожен сервіс пов'язаний зі своїм репозиторієм GitHub. Надсилання змін до main у ChurchApps/Api, ChurchApps/B1Admin або ChurchApps/B1App запускає автоматичне перерозгортання.

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

Витрати

Реальні діапазони для невеликої церкви (до 200 учасників, невеликий трафік):

Компонент	Приблизна вартість на місяць
Базовий план Railway	$5
Плагін MySQL	$5 + ~$1 за сховище
Обчислювальні ресурси 3 вебсервісів	$3–10 разом
Том 1 ГБ	$0.25
Разом	~$15–25/місяць

Витрати зростають пропорційно трафіку, завантаженню фотографій і розміру бази даних. Railway показує поточне використання на вкладці Usage проєкту — встановіть там ліміти витрат, щоб обмежити ризики.

Усунення несправностей

Симптом	Імовірна причина	Виправлення
Збірка завершується з помилкою EBUSY: rmdir '/app/node_modules/.cache'	Конфлікт кешу Nixpacks	Встановіть NIXPACKS_NO_CACHE=true на відповідному сервісі
Збірка B1Admin завершується з Missing: @types/...	Застарілий package-lock.json	Отримайте останню версію main
Розгортання Api зависає на «Deploying»	Перевірка стану не проходить — /health не повертає 200	Перегляньте журнали розгортання; зазвичай бракує обов'язкової змінної середовища
B1Admin показує «перевірте свою пошту», але лист не приходить	MAIL_SYSTEM=SMTP встановлено, але облікові дані відсутні або неправильні	Виправте облікові дані або видаліть MAIL_SYSTEM, щоб вимкнути електронну пошту
Вхід перенаправляє на api.churchapps.org	REACT_APP_STAGE має значення prod	Встановіть REACT_APP_STAGE=custom на сервісі B1Admin
Усі церкви з піддоменами показують однаковий вміст	REACT_APP_B1_WEBSITE_URL не містить токена {subdomain}	Встановіть, наприклад, https://{subdomain}.yourchurch.org
Власний домен показує «Application not found»	DNS ще не поширився або сертифікат Railway очікує	Зачекайте 5 хвилин; перевірте DNS командою dig admin.yourchurch.org

Якщо ви зіткнулися з чимось, чого немає в цьому списку, відкрийте issue на github.com/ChurchApps/Api/issues і додайте журнали розгортання.

Пов'язані статті

• Самостійне розгортання з Docker — той самий стек на вашому власному обладнанні або VPS
• Початкове налаштування — перші кроки після створення вашої церкви
• Початкове налаштування вебсайту — налаштуйте публічний сайт вашої церкви
• Налаштування пожертв — підключіть Stripe або PayPal
• Локальне налаштування API — запуск стеку локально для розробки
• Розгортання API (AWS) — як розгорнуто офіційний SaaS ChurchApps