Loomix
مستنداتبخش برنامه نویساناجرا و راه‌اندازی پروژه (داکر)

راهنمای کامل اجرا، راه‌اندازی و دپلوی با Docker Compose

این راهنما مراحل گام‌به‌گام برای انتقال فایل‌ها، پیکربندی و اجرای تمامی سرویس‌های پروژه شامل زیرساخت، Strapi CMS، Medusa 2.0، Storefront (Next.js) و سیستم پایش OpenObserve را روی سرور مجازی (VPS) یا ماشین مجازی محلی با داکر ارائه می‌دهد.

به دلیل مصرف بالای پردازنده و رم در زمان بیلد Next.js و Strapi، فرایند استقرار در ۱۰ فاز کنترل‌شده طراحی شده است تا از کرش سرور جلوگیری شود.

۱. پیش‌نیازها و مجوزهای داکر

مطمئن شوید ابزارهای زیر روی VPS یا VM شما نصب باشند:

  • Docker و Docker Compose (v2) (نصب سریع روی اوبونتو/دبیان: curl -fsSL https://get.docker.com | sudo sh)
  • Git (جهت کلون مستقیم ریپازیتوری)

مجوز دسترسی به داکر (docker.sock):

روی سرور تازه ممکن است با خطای permission denied while trying to connect to the docker API at unix:///var/run/docker.sock مواجه شوید. این دستورات را برای افزودن یوزر به گروه داکر اجرا کنید:

مجوز دسترسی به داکر (docker.sock):
bash
# ۱. افزودن یوزر به گروه داکر:
sudo usermod -aG docker $USER
 
# ۲. اعمال دسترسی جدید (یا یک‌بار خروج و ورود به SSH):
newgrp docker
 
# ۳. تست اجرای داکر بدون sudo:
docker ps

۲. انتقال سورس‌کد به سرور VPS

قبل از تنظیم GitHub Actions، باید کدهای پروژه را به سرور لینوکسی منتقل کنید. دو روش اصلی وجود دارد:

روش ۱: استفاده از Git (پیشنهادی)

ریپازیتوری عمومی (Public):

کلون ریپازیتوری عمومی (Git Clone)
bash
git clone https://github.com/<YOUR_GITHUB_USERNAME>/<YOUR_REPOSITORY_NAME>.git
cd <YOUR_REPOSITORY_NAME>

ریپازیتوری خصوصی (استفاده از SSH Key - پیشنهادی):

  • ۱. ساخت کلید در سرور: ssh-keygen -t ed25519 -C "your_email@example.com"
  • ۲. نمایش و کپی کلید عمومی: cat ~/.ssh/id_ed25519.pub
  • ۳. افزودن کلید در گیت‌هاب: مسیر GitHub > Settings > SSH and GPG keys > New SSH key (عنوان: VPS Server).
  • ۴. کلون با SSH روی سرور:
کلون ریپازیتوری از طریق SSH
bash
git clone git@github.com:<YOUR_GITHUB_USERNAME>/<YOUR_REPOSITORY_NAME>.git
cd <YOUR_REPOSITORY_NAME>

روش جایگزین برای ریپازیتوری خصوصی (Personal Access Token با دسترسی 'repo'):

کلون ریپازیتوری از طریق توکن شخصی (PAT)
bash
git clone https://<YOUR_GITHUB_USERNAME>:<PERSONAL_ACCESS_TOKEN>@github.com/<YOUR_GITHUB_USERNAME>/<YOUR_REPOSITORY_NAME>.git
cd <YOUR_REPOSITORY_NAME>

روش ۲: انتقال مستقیم با SCP / Rsync

در صورت استفاده از لینوکس یا مک، این دستور را در ترمینال سیستم محلی خود اجرا کنید:

انتقال فایل‌ها به سرور با دستور Rsync
bash
rsync -avz --exclude 'node_modules' --exclude '.git' --exclude '.next' ./ user@your_vps_ip:/root/next-strapi-medusa

⚡ ۳. راه‌اندازی سریع: اسکریپت هوشمند راه‌اندازی سرور (پیشنهادی)

به جای اجرای دستی تک‌تک فازها، اسکریپت هوشمند و خودکار راه‌اندازی سرور را اجرا نمایید. این اسکریپت به صورت گام‌به‌گام شما را در انتخاب پروفایل (A/B/C) هدایت کرده، تمامی کلیدهای رمزنگاری را خودکار تولید می‌کند، فایل .env را پیکربندی کرده، سرویس‌ها را به ترتیب اجرا، سلامت کانتینرها را بررسی، کلیدهای میلی‌سرچ را استخراج، کاربر ادمین را ساخته و داده‌های نمونه را لود می‌کند:

ویزارد تعاملی راه‌اندازی سرور VPS
bash
chmod +x server-setup.sh
bash server-setup.sh
نکته حرفه‌ای
در صورتی که ترجیح می‌دهید مراحل را دستی و فاز به فاز انجام دهید یا نیاز به عیب‌یابی سرویس خاصی دارید، راهنمای مرحله‌به‌مرحله زیر را دنبال کنید.

۴. انتخاب پروفایل استقرار و تنظیم متغیرهای محیطی (.env)

پس از قرارگیری در پوشه پروژه روی سرور، فایل متغیرها را کپی و ویرایش کنید:
cp .env.example .env && nano .env

قبل از اجرای هر فازی، یکی از ۳ پروفایل زیر را انتخاب کنید. آدرس‌های عمومی در زمان بیلد در استراپی، مدوسا و استورفرانت کامپایل می‌شوند و انتخاب اشتباه نیازمند بیلد مجدد خواهد بود.

آیا به دامنه یا کلودفلر نیاز دارید؟
خیر — برای تست‌های محلی یا ماشین مجازی نیازی نیست. کل استک به صورت کامل روی IP سرور قابل اجرا است. کلودفلر فقط برای انتشار دامنه‌های عمومی روی اینترنت واقعی کاربرد دارد.
پیشنهادی برای تست، دموی رزومه و ماشین‌های مجازی لوکال

بهترین گزینه برای تست‌های جامع، نمونه‌کار و ارزیابی سیستم. از Caddy داخل داکر با دامنه‌های .local و SSL خودکار استفاده می‌کند. پنل مدوسا در حالت پروداکشن واقعی و بدون هک کوکی کار می‌کند.

چک‌لیست پروفایل B (به همین ترتیب):

  • ۱. قبل از هر docker compose up: متغیرهای .env را مطابق پروفایل B زیر تنظیم کنید
  • ۲. فاز ۱: اجرای زیرساخت (postgres, redis, meilisearch, minio, minio-setup)
  • ۳. فاز ۲: اجرای Caddy با docker compose up -d caddy (بلافاصله بعد از فاز ۱، قبل از استراپی و مدوسا)
  • ۴. روی سیستم ویندوز شما: افزودن آی‌پی سرور در C:\Windows\System32\drivers\etc\hosts:
    192.168.1.103 store.local api.local admin.local search.local analytics.local monitor.local
  • ۵. فاز ۳ به بعد: اجرای استراپی، مدوسا، استورفرانت، Umami و OpenObserve طبق روال عادی
.env (قطعه کد پروفایل B - پیشنهادی)
env
# Profile B: VM / LAN HTTPS (.local hostnames) - Recommended ★
 
STOREFRONT_PUBLIC_URL=https://store.local
MEDUSA_BACKEND_PUBLIC_URL=https://api.local
STRAPI_PUBLIC_URL=https://admin.local
MEILISEARCH_PUBLIC_URL=https://search.local
MINIO_PUBLIC_URL=https://api.local/minio/mystore
GOOGLE_CALLBACK_URL=https://store.local/ir/account/auth/callback
 
STOREFRONT_URL=http://storefront:8000
MEDUSA_NODE_ENV=production
MEDUSA_ALLOW_HTTP_COOKIES=false
CLOUDFLARE_TUNNEL_TOKEN=
آدرس‌های ادمین (پروفایل B):
• مدوسا: https://api.local/app
• استراپی: https://admin.local/admin
• استورفرانت: https://store.local
• موتور جستجو: https://search.local
• آنالیتیکس: https://analytics.local
• مانیتورینگ: https://monitor.local

🛡️ راهنمای جامع DNS کلودفلر و امن‌سازی لبه شبکه (Edge Hardening)

۱. اقدامات قبل از اجرای پروژه (تنظیم اولیه‌ی رکوردهای DNS):

در داشبورد کلودفلر (بخش DNS > Records)، رکوردهای نوع A را به سمت آی‌پی سرور VPS برای مقادیر @ (دامنه اصلی)، www، api، admin، search، analytics و monitor ایجاد کنید.

بسیار حیاتی: در زمان راه‌اندازی اولیه، وضعیت پراکسی کلودفلر را روی DNS Only (ابر خاکستری) قرار دهید تا Caddy بتواند چالش ACME HTTP-01 / TLS-ALPN را بدون اختلال کامل کرده و گواهی رایگان SSL صادر نماید.

۲. اقدامات پس از فعال شدن سرویس‌ها (امن‌سازی لایه پروداکشن):

• حالت رمزنگاری SSL/TLS: تنظیم روی Full (Strict) در بخش SSL/TLS > Overview.
• گواهی‌های لبه (Edge Certificates): فعال‌سازی گزینه‌های Always Use HTTPS، Automatic HTTPS Rewrites و حداقل نسخه TLS 1.2.
• پراکسی ابر نارنجی (Proxied): تغییر تمامی رکوردها به ابر نارنجی جهت استفاده از CDN و پنهان‌سازی آی‌پی اصلی سرور در برابر حملات DDoS.
• امنیت و فایروال (WAF): فعال‌سازی قابلیت Bot Fight Mode.
• شبکه (Network): اطمینان از فعال بودن WebSockets و gRPC.
• کشینگ (Caching): در بخش Caching > Configuration اطمینان حاصل کنید Browser Cache TTL روی Respect Existing Headers باشد تا سبد خرید و موجودی به صورت لحظه‌ای بروز بمانند.

محافظت لبه با احراز هویت HTTP Basic Auth در Caddy:

• پنل ادمین استراپی (admin.yourdomain.com/admin* و /): با لایه امنیتی HTTP Basic Auth محافظت می‌شود. روت‌های عمومی API (/api/*) و فایل‌های چندرسانه‌ای (/uploads/*) باز می‌مانند تا فرانت‌اند بدون خطای ۴۰۱ اطلاعات را واکشی کند.
• داشبورد مانیتورینگ OpenObserve (monitor.yourdomain.com): با Basic Auth دو لایه محافظت می‌شود.

جهت تولید هش امن bcrypt برای مقدار BASIC_AUTH_HASH در فایل .env دستور زیر را اجرا کنید:

تولید هش پسورد Bcrypt برای Caddy
bash
docker run --rm caddy:latest caddy hash-password --plaintext "your_secret_password"

جدول مرجع یکپارچه آدرس‌های سرور (URL Matrix)

سرویسپروفایل A (محلی HTTP)پروفایل B (محلی HTTPS)پروفایل C (پروداکشن واقعی)
فروشگاه (Storefront)http://<VM_IP>:8000https://store.localhttps://yourdomain.com
پنل ادمین مدوسا (Medusa)http://<VM_IP>:9000/apphttps://api.local/apphttps://api.yourdomain.com/app
پنل ادمین استراپی (Strapi)http://<VM_IP>:1337/adminhttps://admin.local/adminhttps://admin.yourdomain.com/admin
آنالیتیکس (Umami)http://<VM_IP>:3005https://analytics.localhttps://analytics.yourdomain.com
پایش سیستم (OpenObserve)http://<VM_IP>:5080https://monitor.localhttps://monitor.yourdomain.com
موتور جستجو (Meilisearch)127.0.0.1:7700https://search.localhttps://search.yourdomain.com

معنای هر یک از آدرس‌های عمومی در .env:

  • STOREFRONT_PUBLIC_URL: فروشگاه Next.js (پورت ۸۰۰۰ داخل داکر)
  • MEDUSA_BACKEND_PUBLIC_URL: API مدوسا و پنل ادمین (/app)
  • STRAPI_PUBLIC_URL: پنل ادمین استراپی (/admin)؛ لینک‌های پیش‌نمایش از STOREFRONT_PUBLIC_URL استفاده می‌کنند
  • MEILISEARCH_PUBLIC_URL: آدرس عمومی موتور جستجو برای سرچ آنی کلاینت (پروفایل A: http://127.0.0.1:7700، پروفایل B: https://search.local، پروفایل C: https://search.yourdomain.com)
  • MINIO_PUBLIC_URL: پیشوند عمومی تصاویر (پروفایل A: http://IP:9001/mystore و پروفایل B/C: https://api.*/minio/mystore)
  • STOREFRONT_URL: آدرس داخلی داکر (http://storefront:8000) برای پاکسازی کش استورفرانت از سمت مدوسا

تنظیم این موارد قبل از فاز ۱ الزامی است:

• کلیدهای رمزنگاری (openssl rand -hex 32): POSTGRES_PASSWORD، MEILI_MASTER_KEY، توکن‌های راز STRAPI_*، MEDUSA_JWT_SECRET، MEDUSA_COOKIE_SECRET، REVALIDATE_SECRET، UMAMI_APP_SECRET.
• اطلاعات ورود ادمین‌ها: MEDUSA_ADMIN_EMAIL، MEDUSA_ADMIN_PASSWORD، MINIO_ROOT_USER، MINIO_ROOT_PASSWORD، UMAMI_USERNAME، UMAMI_PASSWORD.
• آدرس‌های عمومی: انتخاب پروفایل A، B یا C در جدول زیر.

این متغیرها تا رسیدن به فاز مربوطه باید خالی بمانند:

• فاز ۴: STRAPI_API_TOKEN_FOR_MEDUSA، STRAPI_API_TOKEN_FOR_FRONT
• فاز ۶: MEDUSA_PUBLISHABLE_KEY
• فاز ۷: MEILI_SEARCH_KEY
• فاز ۸: UMAMI_WEBSITE_ID

قانون طلایی پنل Medusa: همیشه MEDUSA_NODE_ENV=production را در داکر نگه دارید. هرگز development نگذارید زیرا پنل ادمین به صورت پروداکشن بیلد شده و حالت توسعه باعث صفحه سفید می‌شود.

۵. بیلد اولیه بک‌اند در GitHub Actions و ورود به داکر

قبل از شروع سرویس‌ها روی سرور، ایمیج‌های بک‌اند را در GitHub Actions بیلد کنید تا سرور بتواند آن‌ها را دانلود کند:

  1. ۱. به تب Actions در ریپازیتوری گیت‌هاب بروید و ورک‌فلوها را فعال کنید.
  2. ۲. ورک‌فلو Build and Push Strapi Image را انتخاب کرده و Run workflow را بزنید.
  3. ۳. ورک‌فلو Build and Push Medusa Image را انتخاب کرده و Run workflow را بزنید.
  4. ۴. (در صورت خصوصی بودن ریپازیتوری) در گیت‌هاب یک Personal Access Token (Classic) با تیک دسترسی‌های repo، workflow و read:packages بسازید و وارد رجیستری داکر سرور شوید:
لاگین به داکر رجیستری در سرور VPS
bash
echo "<YOUR_PAT>" | docker login ghcr.io -u <YOUR_GITHUB_USERNAME> --password-stdin

مرور کلی فازها در یک نگاه

فازسرویس اجراییپروفایل Aپروفایل B و C
فاز 1Postgres, Redis, MinIO, Meilisearch✅✅
فاز 2Caddy (داکر) + فایل hosts در پروفایل B⏭ رد می‌شود✅ بلافاصله بعد از فاز ۱، قبل از استراپی
فاز 3Strapi CMS (دریافت از GHCR)✅✅
فاز 4تولید توکن‌های API استراپی -> فایل .env✅✅
فاز 5بک‌اند Medusa (دریافت از GHCR)✅✅
فاز 6کلید Publishable مدوسا -> فایل .env✅✅
فاز 7کلید جستجوی Meilisearch -> فایل .env✅✅
فاز 8آنالیتیکس Umami (قبل از بیلد استورفرانت)اختیاری✅
فاز 9استورفرانت Next.js (بیلد و دیپلوی خودکار CI/CD)✅✅
فاز 10پایش و مانیتورینگ (OpenObserve, Vector, cAdvisor)اختیاری✅ پیشنهادی

فاز ۱: راه‌اندازی زیرساخت‌ها (Infrastructure)

فقط دیتابیس و سرویس‌های هسته‌ای را اجرا کنید. داده‌ها در ولوم‌های داکر ذخیره و پایدار می‌مانند:

فاز ۱ - اجرای زیرساخت
bash
docker compose up -d postgres redis meilisearch minio minio-setup

صبر کنید تا تمام سرویس‌ها سالم (healthy) شوند: docker compose ps

فاز ۲: درگاه HTTPS (Caddy) و امنیت لبه

پروفایل A: این فاز را کاملاً رد کنید.
پروفایل B و C: این فاز را بلافاصله بعد از فاز ۱ و قبل از اجرای Strapi یا Medusa اجرا کنید.

Caddy به صورت یک کانتینر داکر سبک اجرا می‌شود و مدیریت خودکار گواهینامه‌های SSL، هدرهای امنیتی HSTS/CSP و احراز هویت HTTP Basic Auth را بر عهده دارد.

فاز ۲ - اجرای Caddy
bash
docker compose up -d caddy
docker compose logs -f caddy

تنظیم فایل hosts ویندوز برای پروفایل B:

فایل C:\Windows\System32\drivers\etc\hosts را با دسترسی Administrator در Notepad باز کرده و خط زیر را اضافه کنید:
192.168.1.103 store.local api.local admin.local analytics.local monitor.local
(آی‌پی 192.168.1.103 را با آی‌پی ماشین مجازی خود جایگزین کنید. Meilisearch را اضافه نکنید چون کاملاً داخلی است).

فاز ۳: دریافت و اجرای Strapi CMS

پس از آماده بودن زیرساخت (و Caddy در پروفایل B/C)، ایمیج از پیش ساخته‌شده را از GitHub Packages پول کرده و اجرا کنید:

فاز ۳ - دریافت و اجرای استراپی
bash
docker compose pull strapi
docker compose up -d strapi
docker compose logs -f strapi

صبر کنید تا سرور روی پورت 1337 آماده شود (معمولاً ۱ تا ۳ دقیقه در اولین اجرا). پنل ادمین را باز کنید (پروفایل B: https://admin.local/admin یا پروفایل A: http://<VM_IP>:1337/admin) و کاربر ادمین را بسازید.

فاز ۴: تولید توکن‌های API در Strapi

مدوسا و استورفرانت قبل از اجرا نیازمند توکن‌های API استراپی هستند:

  1. ۱. در پنل استراپی به مسیر Settings > API Tokens بروید.
  2. ۲. برای مدوسا (STRAPI_API_TOKEN_FOR_MEDUSA): روی توکن Full Access کلیک کرده، Regenerate را بزنید و توکن جدید را در STRAPI_API_TOKEN_FOR_MEDUSA در فایل .env بگذارید (یا در ویزارد وارد کنید).
  3. ۳. برای استورفرانت (STRAPI_API_TOKEN_FOR_FRONT): روی توکن Read-Only کلیک کرده، Regenerate را بزنید و در STRAPI_API_TOKEN_FOR_FRONT قرار دهید.

فاز ۵: دریافت و اجرای Medusa Backend

ایمیج از پیش ساخته‌شده مدوسا را از گیت‌هاب پول کرده و اجرا نمایید:

فاز ۵ - دریافت و اجرای مدوسا
bash
docker compose pull medusa
docker compose up -d medusa
docker compose logs -f medusa

عملیات خودکار در اولین اجرا: اجرای مایگریشن‌ها با db:migrate (۲ تا ۵ دقیقه) -> ساخت کاربر ادمین -> راه‌اندازی API روی پورت ۹۰۰۰. پنل ادمین را در آدرس https://api.local/app (پروفایل B) یا http://<VM_IP>:9000/app (پروفایل A) با اطلاعات MEDUSA_ADMIN_EMAIL و MEDUSA_ADMIN_PASSWORD باز کنید.

فاز ۶: ساخت کلید Publishable API Key در Medusa

تولید کلید استورفرانت در پنل مدوسا و اتصال الزامی به کانال فروش:

  1. ۱. در پنل ادمین مدوسا (/app) به مسیر Settings > API Keys > Create Key بروید.
  2. ۲. نام کلید را Storefront گذاشته و مقدار pk_... را در MEDUSA_PUBLISHABLE_KEY در فایل .env قرار دهید (یا در ویزارد وارد کنید).
  3. ۳. بسیار حیاتی: وارد کلید ساخته‌شده شوید، به تب Sales Channels رفته و آن را به Default Sales Channel متصل کنید (بدون این مرحله محصولات روی سایت نشان داده نمی‌شوند).

فاز ۷: استخراج کلید Search-only موتور Meilisearch

استورفرانت برای جستجوی لحظه‌ای فقط باید از کلید جستجو (Search-only Key) استفاده کند و هرگز نباید MEILI_MASTER_KEY در فرانت قرار گیرد. استعلام مستقیم از پورت لوکال‌هاست سرور انجام می‌شود:

فاز ۷ - استعلام کلیدهای Meilisearch
bash
curl -H "Authorization: Bearer <MEILI_MASTER_KEY>" http://127.0.0.1:7700/keys

مقدار Default Search API Key را در MEILI_SEARCH_KEY در فایل .env بگذارید (در اسکریپت ویزارد خودکار استخراج می‌شود).

فاز ۸: آنالیتیکس Umami (قبل از بیلد استورفرانت)

به این دلیل Umami را قبل از استورفرانت اجرا می‌کنیم که Next.js در زمان بیلد در GitHub Actions به Website ID نیاز دارد:

فاز ۸ - اجرای Umami
bash
docker compose up -d umami

پنل Umami را باز کنید (پروفایل B: https://analytics.local یا پروفایل A: http://<VM_IP>:3005)، با admin / umami وارد شوید، سایت جدید تعریف کنید و Website ID صادرشده را در UMAMI_WEBSITE_ID در فایل .env قرار دهید.

فاز ۹: راه‌اندازی GitHub Actions و بیلد Storefront

تنظیم متغیرهای امنیتی در گیت‌هاب و اتصال Self-Hosted Runner روی سرور VPS برای بیلد و دیپلوی خودکار:

گام ۱: تنظیم GitHub Environment Secrets (بخش production)

در ریپازیتوری گیت‌هاب به مسیر Settings > Environments > New environment ('production') بروید و روی Add environment secret کلیک کنید تا متغیرهای زیر را تعریف نمایید:

۱. متغیر STOREFRONT_BUILD_ARGS (متغیرهای زمان کامپایل فرانت‌اند)

شامل تمامی کلیدها و آدرس‌های عمومی فرانت‌اند است. تمپلیت بالا را کپی کرده و کلیدهای تولیدشده در فازهای قبل را درون آن قرار دهید.

قالب متغیرهای STOREFRONT_BUILD_ARGS
env
MEDUSA_BACKEND_URL=http://medusa:9000
NEXT_PUBLIC_MEDUSA_BACKEND_URL=https://api.yourdomain.com
NEXT_PUBLIC_STRAPI_URL=https://admin.yourdomain.com
NEXT_PUBLIC_BASE_URL=https://store.yourdomain.com
NEXT_PUBLIC_MEILISEARCH_HOST=https://search.yourdomain.com
NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY=pk_...
NEXT_PUBLIC_MEILISEARCH_SEARCH_KEY=...
NEXT_PUBLIC_UMAMI_WEBSITE_ID=...
NEXT_PUBLIC_DEFAULT_REGION=IR
DEFAULT_LOCALE=fa-IR
NEXT_PUBLIC_MEILISEARCH_INDEX_NAME=products
NEXT_PUBLIC_ENABLE_IRAN_FEATURES=true

۲. متغیر REGISTRY_URL (آدرس رجیستری کامپوننت‌ها)

آدرس ریپازیتوری کامپوننت‌ها. پیش‌فرض: ریپازیتوری عمومی Loomix Blocks (رایگان و بدون نیاز به توکن):
https://raw.githubusercontent.com/landa33/loom-blocks-registry/main/src/modules

۳. متغیر GITHUB_PAT (اختیاری)

توکن دسترسی شخصی گیت‌هاب (PAT Classic). تیک دسترسی‌های repo، workflow و read:packages الزامی است. این توکن برای دانلود کانتینرها از GHCR، فعال‌سازی CI/CD و دسترسی به ریپازیتوری‌های اختصاصی استفاده می‌شود.

۴. متغیر DEPLOY_PATH (مسیر مطلق پروژه روی سرور)

مسیر کامل و مطلق پوشه پروژه روی لینوکس VPS شما (مانند /root/loomix-commerce). این متغیر برای پیدا کردن پوشه پروژه توسط Self-Hosted Runner الزامی است.

گام ۲: نصب Self-Hosted Runner روی VPS

در گیت‌هاب به Settings > Actions > Runners > New self-hosted runner (Linux) بروید. دستورات را روی سرور اجرا کنید، سپس با sudo ./svc.sh install && sudo ./svc.sh start آن را به عنوان سرویس دائمی فعال نمایید.

گام ۳: اجرای بیلد استورفرانت

در تب Actions گیت‌هاب، ورک‌فلو Build and Push Storefront Image را انتخاب کرده و Run workflow را بزنید.

گام ۴: اجرای استورفرانت روی سرور

فاز ۹ - اجرای کانتینر استورفرانت
bash
docker compose pull storefront
docker compose up -d storefront

فاز ۱۰: مانیتورینگ و پایش پایداری سیستم (OpenObserve)

استک سبک، سریع و پروداکشن برای مشاهده‌پذیری و لاگ‌گیری متمرکز بر پایه OpenObserve، Vector، cAdvisor و docker-stats-exporter:

فاز ۱۰ - اجرای استک پایش سیستم
bash
docker compose up -d openobserve vector cadvisor docker-stats-exporter

داشبورد OpenObserve:

آدرس https://monitor.yourdomain.com (پروفایل C) یا https://monitor.local (پروفایل B) یا http://<VM_IP>:5080 (پروفایل A) را باز کرده و با مشخصات روت OpenObserve وارد شوید.

استریم‌های جمع‌آوری داده‌ها:

docker_logs: تجمیع تمامی لاگ‌های stdout و stderr کانتینرها با قابلیت جستجوی تمام‌متن.

caddy_access: ثبت زنده ترافیک وب، آی‌پی‌های ورودی، کدهای وضعیت HTTP (۲xx/۴xx/۵xx)، میزان تاخیر و مسیر درخواست‌ها مستقیماً از وب‌سرور Caddy توسط Vector.

docker_stats: درصد لحظه‌ای مصرف CPU، رم و ترافیک شبکه (I/O) به تفکیک هر کانتینر.

host_metrics: اطلاعات سیستمی سرور شامل فشار بار پردازنده، میزان پر بودن رم و دیسک سخت.

هشدارهای تلگرامی (Telegram Alerts):

در پنل OpenObserve به مسیر Reliability > Destinations رفته و وبهوک ربات تلگرام خود را متصل کنید (https://api.telegram.org/bot<TOKEN>/sendMessage)؛ سپس در بخش Reliability > Alerts قوانین ارسال هشدار در صورت بروز خطا تعریف نمایید.

سینک تنظیمات استورفرانت و کامپوننت‌ها (استراپی به GitHub CI/CD)

این معماری سینک کامل و خودکار مبتنی بر گیت را میان پنل مدیریت استراپی و فروشگاه Next.js برقرار می‌سازد:

۱. سینک تنظیمات ظاهری استورفرانت (storefront-settings.json)

در استراپی زیر بخش Storefront Settings، مدیران می‌توانند استایل کارت محصول (card-1, card-2, card-3)، طرح هدر و فوتر، قالب صفحات، پالت رنگی قالب و تنظیمات سراسری را سفارشی کنند.

• حالت توسعه (NODE_ENV=development): استراپی فایل تنظیمات را مستقیماً روی دیسک لوکال در store/src/lib/config/storefront-settings.json می‌نویسد و فرانت به صورت آنی هات‌لود می‌شود.
• حالت پروداکشن (NODE_ENV=production): استراپی پریست JSON را از طریق API گیت‌هاب کامیت می‌زند. این کامیت پایپ‌لاین‌های build-storefront.yml و deploy-storefront.yml را فعال کرده تا کانتینر به صورت خودکار و بدون داون‌تایم با Self-Hosted Runner آپدیت شود.

۲. سینک ماژولار کامپوننت‌های Loomix Blocks (اسکریپت sync-loom-component.js)

در بخش Storefront Management استراپی، کلیک روی + Add to Storefront (Queue) یا Remove Style (Queue) تغییرات را در صف sync-history.json قرار می‌دهد. با کلیک روی Update Storefront، تنظیمات به طور خودکار همگام شده و بیلد و دیپلوی در GitHub Actions آغاز می‌گردد.

متغیرهای محیطی مورد نیاز سینک در پروداکشن:

این دو متغیر را در website-admin/.env و فایل .env سرور قرار دهید. حتماً دسترسی‌های 'repo' و 'workflow' را به توکن بدهید:

متغیرهای سینک GitHub CI/CD
env
GITHUB_DEPLOY_TOKEN=ghp_your_personal_access_token # با دسترسی‌های 'repo' و 'workflow'
GITHUB_DEPLOY_REPO=your_username/your_repo_name

تغییر پروفایل در حین استقرار (Switching Profiles)

اگر فاز ۱ را با پروفایل A اجرا کرده‌اید و اکنون قصد دارید به پروفایل B بروید، داده‌های فاز ۱ در ولوم‌های داکر کاملاً امن هستند و نیازی به تکرار فاز ۱ نیست؛ فقط کانتینرهای اپلیکیشن به‌روزرسانی می‌شوند.

تغییری که می‌دهیدسرویسی که باید ری‌استارت شود
آدرس‌های عمومی در فایل .envاستراپی، مدوسا و استورفرانت (ابتدا اکشن گیت‌هاب را اجرا و سپس pull کنید)
متغیر MEDUSA_ALLOW_HTTP_COOKIESفقط مدوسا
افزودن Caddy (تبدیل A به B)اجرای Caddy با docker compose up -d caddy و دریافت ایمیج‌های جدید
تنظیم فایل hosts در پروفایل Bهیچ کاری روی سرور نیاز نیست — فقط فایل hosts ویندوز را ویرایش کنید
نمونه سوئیچ بین پروفایل‌ها
bash
# ۱. ویرایش فایل .env (تغییر آدرس‌ها و MEDUSA_ALLOW_HTTP_COOKIES=false):
nano .env
 
# ۲. اجرای Caddy جهت فعال‌سازی HTTPS محلی:
docker compose up -d caddy
 
# ۳. دریافت ایمیج‌های جدید و اجرای سرویس‌ها:
docker compose pull strapi medusa && docker compose up -d strapi medusa

به‌روزرسانی سرور (Push / Pull)

هر سه برنامه (استراپی، مدوسا، استورفرانت) از طریق ورک‌فلوهای GitHub Actions ساخته می‌شوند.

برای Strapi و Medusa، سرور را با دستور زیر آپدیت کنید:
docker compose pull && docker compose up -d

برای Storefront، کامیت کدها یا سینک استایل‌ها در استراپی به صورت خودکار بیلد شده و با Self-Hosted Runner روی سرور دیپلوی می‌شود.

اسکریپت داده‌های نمونه کاتالوگ (توسعه محلی)

برای توسعه محلی یا تست سریع با کانتینرهای فعال، با اجرای setup.sh (لینوکس/مک) یا setup.bat (ویندوز)، دیتابیس‌ها با ریجن‌ها، دسته‌بندی‌ها، کالکشن‌ها و ۳۰ محصول نمونه به همراه وبلاگ‌ها و ترجمه‌ها پر می‌شوند.

اجرای اسکریپت داده‌های نمونه
bash
./setup.sh # روی لینوکس و مک
.\setup.bat # روی ویندوز

مرجع شبکه‌سازی و دامنه‌های پروداکشن

دسترسی مستقیم از پورت‌ها (پروفایل A یا دیباگ):

  • استورفرانت: :8000
  • ای‌پی‌آی و پنل مدوسا: :9000
  • سیستم مدیریت محتوا استراپی: :1337
  • میلی‌سرچ: :7700
  • کنسول MinIO: :9001
  • آمارگیر اومامی: :3005
  • اوپن‌ابزرو: :5080

دامنه‌های Caddy (پروفایل B):

  • https://store.local -> storefront:8000
  • https://api.local -> medusa:9000
  • https://admin.local -> strapi:1337
  • https://analytics.local -> umami:3000
  • https://monitor.local -> openobserve:5080
  • https://api.local/minio/ -> minio:9000

ارتباطات شبکه داخلی داکر:

کانتینرها در شبکه داخلی از طریق نام سرویس خود صحبت می‌کنند (مانند http://storefront:8000، http://medusa:9000، http://meilisearch:7700). سرویس Meilisearch کاملاً داخلی است و هرگز نباید به صورت عمومی منتشر شود.

دستورات کاربردی داکر و نگهداری سرور

مشاهده وضعیت کانتینرها
bash
docker compose ps
مشاهده لاگ‌های زنده
bash
docker compose logs -f medusa
docker compose logs -f strapi
docker compose logs -f storefront
docker compose logs -f openobserve
پاکسازی کش و آزادسازی حافظه دیسک
bash
docker builder prune -f
docker system prune -f
ری‌استارت کامل (با حفظ داده‌های دیتابیس)
bash
docker compose down
docker compose up -d