ডকুমেন্টেশন

VendKit ইনস্টল করুন, চালান আর ডিপ্লয় করুন।

নিজের সার্ভারে VendKit বসান, লোকালি চালান, কনফিগারেশন বুঝুন—তারপর নিশ্চিন্তে ডিপ্লয় করুন। প্রতিটি কমান্ড কপি করার জন্য তৈরি।

VendKit রিপোজিটরির README ও ব্যাকআপ গাইডের সঙ্গে ২১ নভেম্বর, ২০২৬ তারিখে মিলিয়ে যাচাই করা।

এক নজরে

রানটাইম
Docker Compose
ডেটাবেস
PostgreSQL 16+
লোকাল ঠিকানা
localhost:3000
লাইসেন্স
AGPL-3.0
রিপোজিটরি খুলুন
এই পাতায়

এখান থেকে শুরু

VendKit কীভাবে চালাবেন, সেটা বেছে নিন।

সত্যিকারের ইনস্টলেশনের জন্য Linux সার্ভারে Docker Compose ব্যবহার করুন। ডেভেলপমেন্টের জন্য Node.js ও PostgreSQL দিয়ে মনোরিপো লোকালি চালান।

পূর্বশর্ত

শুরু করার আগে হোস্টের যা যা প্রয়োজন জেনে নিন।

VendKit একটি সাধারণ VPS-এ চলার মতোই হালকা, তবু এর জন্য সমর্থিত রানটাইম, একটি ডোমেইন এবং ব্যাকআপ পরিকল্পনা দরকার। ইনস্টল করার আগেই এগুলো ঠিক করে নিন।

প্রোডাকশন সার্ভার

একটি দোকানের জন্য প্রস্তাবিত শুরুর বিন্দু। VendKit কোনো কঠোর ক্যাপাসিটি সীমা ঘোষণা করে না; ডিস্কের আকার নির্ধারণ করুন ছবি ও ব্যাকআপের জায়গা ধরে, শুধু ডেটাবেস নয়।

অপারেটিং সিস্টেম
Docker সমর্থন করে এমন একটি সাম্প্রতিক ৬৪-বিট Linux ডিস্ট্রিবিউশন
কন্টেইনার রানটাইম
Docker Engine এবং Docker Compose প্লাগইন
CPU
কমপক্ষে ২ vCPU; ব্যস্ত দোকানের জন্য ৪ vCPU
মেমরি
কমপক্ষে ২ GB; ৪ GB প্রস্তাবিত
ডিস্ক
২০ GB এবং এর সঙ্গে পণ্যের ছবি ও ব্যাকআপ আর্কাইভের জায়গা
নেটওয়ার্ক
একটি পাবলিক IPv4 বা IPv6 ঠিকানা, একটি ডোমেইন এবং ৮০ ও ৪৪৩ পোর্ট

লোকাল ডেভেলপমেন্ট

কোডবেস নিয়ে কাজ করার সময়েই মনোরেপো ব্যবহার করুন। Docker পথে হোস্টে Node.js বা PostgreSQL লাগে না।

Node.js
২৪ বা নতুন
pnpm
১১ বা নতুন
PostgreSQL
১৬ বা নতুন, লোকালি চলমান
Git
যেকোনো সাম্প্রতিক সংস্করণ

পোর্ট ও এক্সপোজার

Compose শুধু ওয়েব অ্যাপ পাবলিশ করে। API ও ডেটাবেস Docker-এর অভ্যন্তরীণ নেটওয়ার্কেই থাকে।

ওয়েব অ্যাপ
৩০০০, পাবলিশ করা; WEB_PORT দিয়ে বদলান
API
৪০০০, শুধু অভ্যন্তরীণ
PostgreSQL
৫৪৩২, শুধু অভ্যন্তরীণ
HTTPS
রিভার্স প্রক্সিতে ৪৪৩

ডিস্ক পরিকল্পনা

পণ্যের ছবি ও ব্যাকআপ আর্কাইভ ডেটাবেসের চেয়ে দ্রুত বাড়ে। vendkit-data ভলিউমটি টেকসই ডিস্কে রাখুন, খালি জায়গা লক্ষ্য করুন এবং আর্কাইভ সার্ভারের বাইরে কপি করুন। একই ডিস্কে রাখা ব্যাকআপ দুর্যোগ পুনরুদ্ধার নয়।

ইনস্টলের আগে

প্রথম চালুর সময় যেন আটকে না যায়, এগুলো আগে প্রস্তুত রাখুন।

  • একটি Linux হোস্ট যেটি আপনি পরিচালনা করতে পারেন, একটি non-root sudo ব্যবহারকারীসহ
  • Docker Engine ও Compose প্লাগইন ইনস্টল করা
  • সার্ভারের দিকে DNS নির্দেশ করা একটি ডোমেইন নাম
  • একটি TLS সার্টিফিকেট, সাধারণত রিভার্স প্রক্সি ইস্যু করে
  • সার্ভারের বাইরে ব্যাকআপ ও হোস্ট আপডেটের পরিকল্পনা
  • প্রথম অ্যাকাউন্টের জন্য অ্যাডমিনিস্ট্রেটরের নাম ও ইমেইল

হোস্ট যাচাই করুন

ক্লোন করার আগে Docker, Compose ও Git পাওয়া যায় কি না নিশ্চিত করুন। কোনো কমান্ড না থাকলে আগে সেটি ইনস্টল করুন।

টার্মিনাল
docker --version
docker compose version
git --version

লোকাল ডেভেলপমেন্টের জন্য ভাষা ও ডেটাবেস টুলগুলো যাচাই করুন:

টার্মিনাল
node --version
pnpm --version
psql --version

Docker ইনস্টলেশন

ক্লোন থেকে প্রথম সাইন-ইন পর্যন্ত।

Docker ও Compose প্লাগইন থাকা Linux সার্ভারে এই ধাপগুলো অনুসরণ করুন। কনফিগার কমান্ডটি প্রয়োজনীয় সিক্রেট নিজেই তৈরি করে দেয়।

শুরুর আগে

  • Git ইনস্টল করা
  • Compose প্লাগইনসহ Docker
  • vendkit-db ও vendkit-data ভলিউমের জন্য স্থায়ী স্টোরেজ
  • পাবলিক ব্যবহারের জন্য HTTPS-সহ রিভার্স প্রক্সি
  1. 01

    রিপোজিটরি ক্লোন করুন

    সার্ভারে সোর্স ডাউনলোড করুন। এটি GitHub-এ থাকা প্রকাশ্য VendKit রিপোজিটরি।

    টার্মিনাল
    git clone https://github.com/MuawiyahDev/vendkit.git
    cd vendkit
  2. 02

    এনভায়রনমেন্ট ফাইল তৈরি করুন

    প্রয়োজনীয় তিনটি সিক্রেট তৈরি করে টেমপ্লেট থেকে নতুন .env ফাইলে লিখুন। কমান্ডটি ফাইলটিকে শুধু আপনার ইউজারের জন্য সীমাবদ্ধও করে দেয়।

    টার্মিনাল
    POSTGRES_PASSWORD="$(openssl rand -hex 24)"
    JWT_SECRET="$(openssl rand -hex 32)"
    API_KEY="$(openssl rand -hex 32)"
    
    awk -v pw="$POSTGRES_PASSWORD" -v jwt="$JWT_SECRET" -v key="$API_KEY" '
      /^POSTGRES_PASSWORD=/ { print "POSTGRES_PASSWORD=" pw; next }
      /^JWT_SECRET=/        { print "JWT_SECRET=" jwt; next }
      /^API_KEY=/           { print "API_KEY=" key; next }
      { print }
    ' .env.example > .env
    
    chmod 600 .env
  3. 03

    স্ট্যাক চালু করুন

    API কনটেইনার নিজে থেকেই মাইগ্রেশন প্রয়োগ করে। প্রথম বিল্ডে কয়েক মিনিট লাগতে পারে।

    টার্মিনাল
    docker compose up -d --build
  4. 04

    প্রথম অ্যাকাউন্ট তৈরি করুন

    অ্যাপ খুলে অ্যাডমিনিস্ট্রেটর অ্যাকাউন্টটি তৈরি করুন। এরপর পাবলিক রেজিস্ট্রেশন বন্ধ হয়ে যায়।

পাবলিক সার্ভারে চালাচ্ছেন? স্ট্যাক চালু করার আগে .env-এ APP_URL আপনার HTTPS ঠিকানায় সেট করুন। ডিফল্ট http://localhost:3000।

ইনস্টলেশন যাচাই করুন

দুটি কন্টেইনারই যেন সুস্থ দেখায় এবং হেলথ এন্ডপয়েন্ট যেন সফল উত্তর দেয়।

টার্মিনাল
docker compose ps
docker compose exec api wget -qO- http://localhost:4000/api/health

হেলথ চেক ব্যর্থ হলে কনফিগারেশন বদলানোর আগে API লগ পড়ুন।

প্রথম চালুর চেকলিস্ট

অ্যাডমিনিস্ট্রেটর অ্যাকাউন্ট তৈরি হওয়ার পর এই ধাপগুলো সম্পন্ন করুন, যাতে ওয়ার্কস্পেস আপনার বিক্রয় পদ্ধতির সঙ্গে মেলে।

  • Settings → Business profile খুলে ইনভয়েসে ছাপা হওয়া তথ্য যোগ করুন।
  • নাম্বারিং, মুদ্রা প্রদর্শন, পরিশোধের সময় ও শর্তের জন্য Settings → Invoice দেখুন।
  • অর্ডার তৈরির আগে ক্যাটাগরি, ব্র্যান্ড ও পণ্য যোগ করুন।
  • একটি পরীক্ষামূলক গ্রাহক ও অর্ডার তৈরি করে ইনভয়েস PDF ডাউনলোড করুন।
  • একটি ব্যাকআপ ডাউনলোড করে নিশ্চিত করুন আর্কাইভটি ব্যাকআপ ইতিহাসে দেখা যাচ্ছে।

পরে আপগ্রেড করুন

সর্বশেষ সোর্স টেনে আনুন এবং আবার বিল্ড করুন। আগে প্রয়োগ করা মাইগ্রেশন বাদ পড়ে, তাই একই কমান্ড নিরাপদে আবার চালানো যায়।

টার্মিনাল
git pull
docker compose up -d --build

ডেভেলপমেন্ট

VendKit লোকালি চালান।

কোডবেসে কাজ করার সময় এই পথটি ব্যবহার করুন। Node.js 24+, pnpm 11+ ও PostgreSQL 16+ লাগবে।

শুরুর আগে

  • Node.js 24 বা নতুন
  • pnpm 11 বা নতুন
  • PostgreSQL 16 বা নতুন
  • Git
  1. 01

    রিপোজিটরি ক্লোন করুন

    সোর্স ডাউনলোড করে প্রজেক্টের রুটে যান।

    টার্মিনাল
    git clone https://github.com/MuawiyahDev/vendkit.git
    cd vendkit
  2. 02

    ডিপেন্ডেন্সি ইনস্টল করুন

    pnpm দিয়ে ওয়ার্কস্পেস প্যাকেজগুলো ইনস্টল করুন।

    টার্মিনাল
    pnpm install
  3. 03

    ডেটাবেস তৈরি করুন

    vendkit নামে একটি লোকাল PostgreSQL ডেটাবেস তৈরি করুন। createdb বা আপনার PostgreSQL ক্লায়েন্ট ব্যবহার করতে পারেন।

    টার্মিনাল
    createdb vendkit
  4. 04

    এনভায়রনমেন্ট ফাইল তৈরি করুন

    API, ডেটাবেস ও ওয়েবের এনভায়রনমেন্ট টেমপ্লেট কপি করুন। API ও ডেটাবেস ফাইলে একই DATABASE_URL, আর API ও ওয়েবে একই API_KEY রাখুন।

    .env
    cp apps/api/.env.example apps/api/.env
    cp packages/database/.env.example packages/database/.env
    cp apps/web/.env.example apps/web/.env
  5. 05

    মাইগ্রেশন প্রয়োগ করুন

    অ্যাপ চালু করার আগে ডেটাবেস মাইগ্রেশন চালান।

    টার্মিনাল
    pnpm db:migrate
  6. 06

    ডেভেলপমেন্ট সার্ভার চালু করুন

    ওয়েব অ্যাপ ও API ওয়াচ মোডে চালান।

    টার্মিনাল
    pnpm dev

এনভায়রনমেন্ট ফাইল

লোকাল সেটআপে তিনটি ফাইল ব্যবহার হয়: apps/api/.env, packages/database/.env ও apps/web/.env। DATABASE_URL ও API_KEY ফাইলগুলোর মধ্যে মিলিয়ে রাখুন।

কোনো .env ফাইল কমিট করবেন না।

লোকাল ঠিকানা

ওয়েব অ্যাপ
http://localhost:3000
API
http://localhost:4000/api
হেলথ চেক
http://localhost:4000/api/health

দরকারি কমান্ড

  • pnpm devওয়েব ও API-র ডেভেলপমেন্ট সার্ভার
  • pnpm buildওয়ার্কস্পেসের প্রোডাকশন বিল্ড
  • pnpm lintওয়ার্কস্পেস লিন্ট
  • pnpm check-typesওয়ার্কস্পেস টাইপ চেক
  • pnpm testটেস্ট স্যুট চালান
  • pnpm db:migrateডেভেলপমেন্ট মাইগ্রেশন তৈরি বা প্রয়োগ
  • pnpm db:studioPrisma Studio খুলুন

পুল রিকোয়েস্টের আগে

লিন্ট, টাইপ চেক, টেস্ট ও প্রোডাকশন বিল্ড চালান:

টার্মিনাল
pnpm lint && pnpm check-types && pnpm test && pnpm build

কনফিগারেশন

যে ভেরিয়েবলগুলো আসলে দরকার

চালু হওয়ার সময় API প্রয়োজনীয় এনভায়রনমেন্ট ভেরিয়েবল যাচাই করে, আর কোনো সমস্যা থাকলে সব সমস্যার তালিকা দিয়ে বুট হতে অস্বীকার করে। ব্যবসার তথ্য ও ইনভয়েস সেটিংস ডেটাবেসে থাকে।

লোকাল ডেভেলপমেন্ট

লোকাল মান থাকে apps/api/.env, packages/database/.env ও apps/web/.env-এ। Docker রুটের .env ফাইল পড়ে।
DATABASE_URL
API ও Prisma যে PostgreSQL সংযোগ স্ট্রিং ব্যবহার করে।
JWT_SECRET
অ্যাক্সেস টোকেন সাইন করার সিক্রেট, অন্তত ৩২ অক্ষরের।
API_KEY
ওয়েব অ্যাপ API কল করতে যে শেয়ার্ড কী ব্যবহার করে। এটি গোপন রাখুন।
APP_URL
ওয়েব অ্যাপের পাবলিক URL। Compose এটি API-তে অনুমোদিত CORS অরিজিন হিসেবে পাঠায়।
ALLOW_PUBLIC_REGISTRATION
ডিফল্টে বন্ধ। প্রথম অ্যাকাউন্টের পর ইচ্ছাকৃতভাবে সাইন-আপ চালু করতে চাইলে এটি সক্রিয় করুন।
BACKUP_SAFETY_SNAPSHOT
রিস্টোরের আগে সেফটি ব্যাকআপ তৈরি করে। ডিফল্টে চালু।

সম্পূর্ণ এনভায়রনমেন্ট রেফারেন্স

Compose রুটের .env ফাইল পড়ে। Docker-এ API ও ওয়েব সার্ভিস মান পায় Compose থেকে, আর লোকাল ডেভেলপমেন্টে নিজেদের ফাইল থেকে।

Compose (.env)

docker compose পড়ে

POSTGRES_PASSWORD
আবশ্যক
বান্ডল করা PostgreSQL সার্ভিসের পাসওয়ার্ড। শুধু URL-নিরাপদ অক্ষর ব্যবহার করুন; এটি DATABASE_URL-এ বসে।
JWT_SECRET
আবশ্যক (৩২+ অক্ষর)
অ্যাক্সেস টোকেন সাইন করে।
API_KEY
আবশ্যক
ওয়েব অ্যাপ ও API-এর মধ্যে শেয়ার্ড কী।
APP_URL
http://localhost:3000
পাবলিক ওয়েব URL। Compose এটি CORS_ORIGINS হিসেবে API-কে দেয়।
ALLOW_PUBLIC_REGISTRATION
false
প্রথম অ্যাডমিনিস্ট্রেটরের পর সাইন-আপ অনুমোদন করে।
WEB_PORT
3000
ওয়েব কন্টেইনারের জন্য হোস্টে পাবলিশ করা পোর্ট।
APP_VERSION
0.1.0
ব্যাকআপ মেটাডেটায় লেখা সংস্করণ।

API

চালুর সময় যাচাই হয়

DATABASE_URL
আবশ্যক
API ও Prisma-র ব্যবহার করা PostgreSQL সংযোগ স্ট্রিং।
JWT_SECRET
আবশ্যক (৩২+ অক্ষর)
অ্যাক্সেস টোকেন সাইন করে।
API_KEY
আবশ্যক
ওয়েব অ্যাপ ও API-এর মধ্যে শেয়ার্ড কী।
PORT
4000
কন্টেইনারের ভেতরে API পোর্ট।
CORS_ORIGINS
APP_URL থেকে
কমা দিয়ে আলাদা অনুমোদিত ওয়েব অরিজিন। Compose এটি APP_URL থেকে নেয়।
ALLOW_PUBLIC_REGISTRATION
false
প্রথম অ্যাডমিনিস্ট্রেটরের পর সাইন-আপ অনুমোদন করে।
IMAGE_STORAGE_DIR
uploads/images
ছবি আপলোডের ডিরেক্টরি। Compose /data/images সেট করে।
IMAGE_MAX_FILE_SIZE
৫ MB (বাইটে)
সর্বোচ্চ অনুমোদিত ছবি আপলোড।
BACKUP_STORAGE_DIR
uploads/backups
ব্যাকআপ আর্কাইভের ডিরেক্টরি। ছবির ডিরেক্টরির ভেতরে রাখা যাবে না। Compose /data/backups সেট করে।
BACKUP_MAX_FILE_SIZE
১ GB
সর্বোচ্চ অনুমোদিত ব্যাকআপ আপলোড বা আর্কাইভ।
BACKUP_MAX_EXTRACTED_SIZE
২ GB
সর্বোচ্চ আনকম্প্রেসড রিস্টোর।
BACKUP_RESTORE_TRANSACTION_TIMEOUT_MS
১০ মিনিট
স্ন্যাপশট ও রিস্টোর ট্রানজেকশনের সময়সীমা।
BACKUP_SAFETY_SNAPSHOT
true
রিস্টোরের আগে নিরাপত্তা ব্যাকআপ তৈরি করে।
APP_VERSION
0.1.0
ব্যাকআপ মেটাডেটায় লেখা সংস্করণ।

Web

API কী-এর সঙ্গে মিলতে হবে

NEST_API_URL
আবশ্যক
API ভিত্তি URL, /api সহ। Compose http://api:4000/api সেট করে।
API_KEY
আবশ্যক
ওয়েব অ্যাপ ও API-এর মধ্যে শেয়ার্ড কী।
ব্যবসার তথ্য, ইনভয়েস নম্বরিং বা শর্ত এনভায়রনমেন্ট ভেরিয়েবলে রাখবেন না। এগুলোর জায়গা Settings, আর সেগুলো ব্যাকআপে অন্তর্ভুক্ত থাকে।

ডেটা ও ব্যাকআপ

আপনার ডেটা কোথায় থাকে জেনে নিন।

VendKit ব্যবসার রেকর্ড PostgreSQL-এ এবং আপলোড করা ফাইল ডিস্কে রাখে। দুটোই নামযুক্ত Docker ভলিউমে থাকে এবং কন্টেইনার বদলালেও টিকে থাকতে হবে।

vendkit-db

PostgreSQL ডেটা ডিরেক্টরি: পণ্য, গ্রাহক, অর্ডার, পেমেন্ট, ইনভয়েস, ইনভেন্টরি ও সেটিংস।

vendkit-data

আপলোড করা ছবি এবং API কন্টেইনারের লেখা ব্যাকআপ আর্কাইভ।

API কন্টেইনারের ভেতরের পাথ

ব্যাকআপ API হোস্টের ফাইলসিস্টেমে লেখা হয়, কোনো ক্লাউড সেবায় নয়। ব্যাকআপ ডিরেক্টরি ইমেজ ডিরেক্টরির ভেতরে থাকা যাবে না।

/data/images
ইমেজ আপলোড, vendkit-data ভলিউম থেকে মাউন্ট করা।
/data/backups
ব্যাকআপ আর্কাইভ, এটিও vendkit-data ভলিউমে।

ব্যাকআপে কী থাকে

প্রতিটি আর্কাইভ একটি সংস্করণযুক্ত, gzip-কম্প্রেসড tar ফাইল — ম্যানিফেস্ট, চেকসাম ও ব্যবসার ডেটাসহ।

  • ক্যাটাগরি, ব্র্যান্ড, পণ্য ও পণ্যের ছবি
  • গ্রাহক, অর্ডার, অর্ডার আইটেম, পেমেন্ট ও রিটার্ন
  • ইনভয়েস ও ডকুমেন্ট সিকোয়েন্স
  • ইনভেন্টরি মুভমেন্ট ও ব্যবসার সেটিংস
  • ডেটাবেসে উল্লেখ থাকা প্রতিটি আপলোড করা ছবি

কী বাদ দেওয়া হয়

কিছু রেকর্ড ইচ্ছাকৃতভাবে বাদ দেওয়া হয়, যাতে রিস্টোর আপনাকে লক আউট না করে বা নিজের ইতিহাস মুছে না ফেলে।

  • ব্যবহারকারীর অ্যাকাউন্ট, পাসওয়ার্ড হ্যাশ ও রিফ্রেশ টোকেন
  • ব্যাকআপ ও রিস্টোরের ইতিহাস
  • এনভায়রনমেন্ট ভেরিয়েবল, ডেটাবেস URL ও সিক্রেট

সার্ভারে ব্যাকআপের তালিকা

Settings → Backup & Restore থেকে আর্কাইভ তৈরি হয়। API সেগুলো /data/backups-এ লেখে, যেটি vendkit-data ভলিউম।

টার্মিনাল
docker compose exec api ls -lh /data/backups

আর্কাইভ সার্ভারের বাইরে কপি করুন

অ্যাপ থেকে ব্যাকআপ ডাউনলোড করুন, অথবা আর্কাইভ ডিরেক্টরি আপনার ওয়ার্কস্টেশনে কপি করুন। একই হোস্টে রাখা স্টোরেজ যথেষ্ট নয়।

টার্মিনাল
mkdir -p offsite-backups
docker compose cp api:/data/backups/. ./offsite-backups/

ব্যাকআপ রিস্টোর করুন

Settings → Backup & Restore থেকে রিস্টোর করুন। বর্তমান ডেটা বদলানোর আগে আর্কাইভ যাচাই করা হয়।

  1. 1বর্তমান ডেটার একটি নতুন ব্যাকআপ তৈরি করুন, যদিও ডিফল্টভাবে নিরাপত্তা স্ন্যাপশট তৈরি হয়।
  2. 2ব্যাকআপ স্ক্রিন থেকে যে আর্কাইভটি রিস্টোর করতে চান সেটি আপলোড করুন।
  3. 3রিস্টোর নিশ্চিত করুন। ম্যানিফেস্টের সংস্করণ চলমান অ্যাপ্লিকেশনের সঙ্গে মিলতে হবে।
  4. 4কাজটি শেষ হওয়া পর্যন্ত অপেক্ষা করুন এবং ফলাফল ব্যাকআপ ইতিহাসে দেখুন।
  5. 5একটি অর্ডার, একটি ইনভয়েস ও একটি পণ্যের ছবি খুলে রিস্টোর হওয়া ডেটা যাচাই করুন।
রিস্টোর ব্যবসার ডেটা বদলে দেয়। ব্যবহারকারী ও ব্যাকআপ ইতিহাস টিকে থাকে, তবে বদলের সময়ে লেখা নতুন তথ্য সংরক্ষিত থাকার নিশ্চয়তা নেই। কম ব্যবহারের সময়ে রিস্টোর করুন।

স্বয়ংক্রিয় সময়সূচি নেই

এই সংস্করণে কোনো ব্যাকগ্রাউন্ড শিডিউলার নেই। হোস্ট-লেভেল স্ন্যাপশটের জন্য হোস্টের cron বা প্ল্যাটফর্ম শিডিউলার ব্যবহার করুন এবং নিয়মিত আর্কাইভ ডাউনলোড করুন। ব্যাকআপ ডিরেক্টরি API প্রসেসের লেখার অনুমতিসহ টেকসই স্টোরেজে রাখুন।

ডিপ্লয়মেন্ট

VendKit প্রোডাকশনে ডিপ্লয় করুন।

HTTPS-এর পেছনে একটি Compose স্ট্যাক চালান। API প্রাইভেট রাখুন আর দুটি স্থায়ী ভলিউমের ব্যাকআপ রাখুন।

ডিপ্লয়ের আগে

  • Docker ও Compose প্লাগইনসহ Linux সার্ভার
  • সার্ভারের দিকে পয়েন্ট করা একটি ডোমেইন
  • বৈধ TLS সার্টিফিকেটসহ রিভার্স প্রক্সি
  • স্থায়ী স্টোরেজ ও সার্ভারের বাইরে ব্যাকআপের পরিকল্পনা
  1. 01

    পাবলিক URL সেট করুন

    .env-এ APP_URL চূড়ান্ত HTTPS অরিজিনে সেট করুন। এটি CORS ও তৈরি হওয়া লিংকে ব্যবহৃত হয়।

    .env
    APP_URL=https://your-domain.example
  2. 02

    স্ট্যাক চালু করুন

    ওয়েব অ্যাপ, API ও PostgreSQL বিল্ড করে চালু করুন। API কনটেইনার শুরু হলে মাইগ্রেশন নিজে থেকে চলে।

    টার্মিনাল
    docker compose up -d --build
  3. 03

    HTTPS-এর পেছনে রাখুন

    Caddy, nginx বা Traefik-এর মতো রিভার্স প্রক্সিতে TLS শেষ করুন। ট্রাফিক শুধু ওয়েব অ্যাপে পাঠান।

    Caddy কনফিগারেশনের উদাহরণ

    Caddyfile
    vendkit.example.com {
      encode zstd gzip
      reverse_proxy 127.0.0.1:3000
    }

    একটি ইনস্টলেশনের জন্য ন্যূনতম রিভার্স প্রক্সি। আপনার ডোমেইন ও সার্ভার অনুযায়ী বদলে নিন। vendkit.example.com-এর জায়গায় আপনার ডোমেইন দিন। WEB_PORT বদলালে আপস্ট্রিম পোর্টও বদলান।

  4. 04

    ডিপ্লয় যাচাই করুন

    দুটি কনটেইনারই সুস্থ আছে কিনা দেখুন এবং API হেলথ এন্ডপয়েন্ট যাচাই করুন।

    টার্মিনাল
    docker compose ps
    docker compose exec api wget -qO- http://localhost:4000/api/health
  5. 05

    প্রথম অ্যাকাউন্ট তৈরি করুন

    পাবলিক URL খুলে অ্যাডমিনিস্ট্রেটর অ্যাকাউন্ট তৈরি করুন। এরপর পাবলিক রেজিস্ট্রেশন বন্ধ হয়।

নিরাপদে চালান

  • একটি API ইনস্ট্যান্স চালান। রেট লিমিটিং মেমোরিতে থাকে।
  • API পোর্ট পাবলিকভাবে খুলবেন না।
  • vendkit-db ও vendkit-data ভলিউম সংরক্ষণ করুন।
  • হোস্ট ব্যাকআপ নীতির অংশ হিসেবে আর্কাইভ সার্ভারের বাইরে কপি করুন।
  • HTTPS ব্যবহার করুন। প্রোডাকশন সেশন কুকি Secure।

প্রোডাকশন ইনস্টল আপগ্রেড করুন

সর্বশেষ সোর্স টেনে এনে আবার বিল্ড করুন। প্রয়োগ করা মাইগ্রেশন বাদ পড়ে, তাই কমান্ডটি নিরাপদে আবার চালানো যায়।

টার্মিনাল
git pull
docker compose up -d --build

আপগ্রেড

নিরাপদে আপগ্রেড ও রোলব্যাক করুন।

API কন্টেইনার চালু হলে VendKit ডেটাবেস মাইগ্রেশন প্রয়োগ করে। আপডেটের পরিকল্পনা করুন, একটি ভালো ব্যাকআপ রাখুন এবং কাজ শেষ করার আগে স্ট্যাক যাচাই করুন।

আপগ্রেডের আগে

কী চলছে তা লিখে রাখুন এবং বর্তমান ডেটা সুরক্ষিত করুন।

  • যে রিলিজ নোট বা রিপোজিটরি কমিট ডিপ্লয় করবেন সেগুলো পড়ুন।
  • Settings → Backup & Restore থেকে একটি ব্যাকআপ তৈরি করে ডাউনলোড করুন।
  • বর্তমান কমিট নোট করুন, যাতে প্রয়োজনে ফিরে যেতে পারেন।
  • কম ব্যবহারের সময় বেছে নিন; রিবিল্ডের সময় API রিস্টার্ট হয়।
টার্মিনাল
git rev-parse --short HEAD
docker compose exec api ls -lh /data/backups

আপডেট প্রয়োগ করুন

সর্বশেষ সোর্স টেনে আনুন এবং দুটি অ্যাপ্লিকেশন ইমেজ আবার বিল্ড করুন। ডেটাবেস কন্টেইনার চালুই থাকে।

টার্মিনাল
git pull
docker compose up -d --build

আগে প্রয়োগ করা মাইগ্রেশন বাদ দেওয়া হয়, তাই কমান্ডটি বারবার চালানো নিরাপদ। বড় পরিবর্তনের পর প্রথম বিল্ডে কয়েক মিনিট লাগতে পারে।

আপগ্রেডের পর যাচাই

দুটি কন্টেইনারই সুস্থ আছে কি না দেখুন, তারপর সাইন ইন করে একটি অর্ডার, একটি ইনভয়েস ও একটি পণ্যের ছবি যাচাই করুন।

টার্মিনাল
docker compose ps
docker compose exec api wget -qO- http://localhost:4000/api/health

রোলব্যাক

নতুন সংস্করণ ব্যর্থ হলে আগের কমিটে ফিরে গিয়ে আবার বিল্ড করুন। এরপর আপগ্রেডের আগে নেওয়া ব্যাকআপটি রিস্টোর করুন।

টার্মিনাল
git log --oneline -5
git checkout <previous-commit>
docker compose up -d --build
ডেটাবেস মাইগ্রেশন শুধু সামনের দিকে চলে। আপগ্রেডে স্কিমা বদলালে পুরোনো কমিট নতুন ডেটাবেসে নাও চলতে পারে। পুরোনো কোড চালু করার আগে আপগ্রেড-পূর্ব ব্যাকআপ রিস্টোর করুন।

previous-commit এর জায়গায় আপনার নোট করা কমিটটি বসান। নতুন সংস্করণ কয়েক দিন স্থিতিশীল থাকা পর্যন্ত ব্যাকআপটি রাখুন।

অপারেশন

কোনো অপ্রত্যাশিত ঝামেলা ছাড়াই চালান

স্ট্যাক দেখুন, লগ পড়ুন এবং ভলিউমগুলো রেখে দিন। বেশিরভাগ সমস্যা docker compose ps এবং API লগেই ধরা পড়ে।

ব্যাকআপ

Settings → Backup & Restore থেকে সম্পূর্ণ আর্কাইভ তৈরি করুন। হোস্ট ব্যাকআপের রুটিনের অংশ হিসেবে আর্কাইভগুলো সার্ভারের বাইরেও কপি করুন।

হেলথ চেক

GET /api/health কনটেইনার ও মনিটরিংয়ের জন্য API এবং ডেটাবেসের অবস্থা জানায়।

ডিপ্লয়মেন্ট

API পোর্ট পাবলিকভাবে খুলবেন না। একটিই API ইনস্ট্যান্স চালান, দুটি ভলিউম সংরক্ষণ করুন এবং রিভার্স প্রক্সিতে HTTPS শেষ করুন।

রিস্টোর

রিস্টোর আর্কাইভ যাচাই করে এক ট্রানজ্যাকশনে ব্যবসার ডেটা বদলায়। ডিফল্টে আগে সেফটি স্ন্যাপশট তৈরি হয়।

প্রতিদিনের কমান্ড

সার্ভারের রিপোজিটরি রুট থেকে এগুলো চালান।

  • docker compose psকন্টেইনারের অবস্থা ও স্বাস্থ্য
  • docker compose logs -f --tail=100 apiAPI লগ অনুসরণ করুন; Next.js অ্যাপের জন্য web ব্যবহার করুন
  • docker compose restart apiরিবিল্ড না করেই একটি সার্ভিস রিস্টার্ট করুন
  • docker compose exec api wget -qO- http://localhost:4000/api/healthAPI ও ডেটাবেসের অবস্থা জিজ্ঞাসা করুন
  • docker system dfছবি ও কন্টেইনার কত জায়গা নিচ্ছে দেখুন
  • docker compose downকন্টেইনার ও নেটওয়ার্ক বন্ধ ও সরান; ভলিউম থাকে
  • docker compose up -dবিদ্যমান কন্টেইনার আবার চালু করুন
ডেটাবেস ও সব আপলোড করা ফাইল মুছে ফেলার ইচ্ছা না থাকলে docker compose down-এ কখনো --volumes যোগ করবেন না। শুধু ইনস্টলেশন ইচ্ছাকৃতভাবে ধ্বংস করার সময় এটি ব্যবহার করুন।

এই সংস্করণে স্বয়ংক্রিয় ব্যাকআপ শিডিউলার বা ব্যাকগ্রাউন্ড ওয়ার্কার নেই। হোস্ট cron ও সার্ভারের বাইরে কপি রাখার দায়িত্ব আপনার।

নিরাপত্তা

সেলফ-হোস্টেড ইনস্টলেশন সুরক্ষিত করুন।

সার্ভার, সিক্রেট ও ডেটার নিয়ন্ত্রণ আপনার হাতে। একটি বাস্তব দোকানের জন্য ন্যূনতম এগুলো অনুসরণ করুন।

HTTPS ব্যবহার করুন

প্রোডাকশনের সেশন কুকি Secure হিসেবে চিহ্নিত থাকে। সাধারণ HTTP-তে ব্যবহারকারী সাইন ইন করতে পারবে না। রিভার্স প্রক্সিতে TLS শেষ করুন এবং HTTP-কে HTTPS-এ রিডাইরেক্ট করুন।

API গোপন রাখুন

শুধু ওয়েব অ্যাপ পাবলিশ হয়। ব্রাউজার Next.js-কে ডাকে, যা শেয়ার্ড কী দিয়ে API-তে প্রক্সি করে। ৪০০০ পোর্ট পাবলিশ করবেন না।

সিক্রেট সুরক্ষিত রাখুন

POSTGRES_PASSWORD, JWT_SECRET ও API_KEY-এর জন্য দীর্ঘ র‍্যান্ডম মান ব্যবহার করুন। .env ফাইল mode 600-এ রাখুন, কখনো কমিট করবেন না এবং একই মান একাধিক ইনস্টলেশনে ব্যবহার করবেন না।

রেজিস্ট্রেশন বন্ধ রাখুন

প্রথম অ্যাকাউন্টটি অ্যাডমিনিস্ট্রেটর হয় এবং এরপর পাবলিক সাইন-আপ বন্ধ হয়ে যায়। ইচ্ছাকৃতভাবে স্ব-সেবা অ্যাকাউন্ট চাইলে তবেই ALLOW_PUBLIC_REGISTRATION চালু করুন।

ব্যবহারকারী পরিচালনা করুন

অ্যাডমিনিস্ট্রেটররা Team থেকে সদস্য তৈরি ও পাসওয়ার্ড রিসেট করতে পারেন। আর প্রয়োজন নেই এমন অ্যাক্সেস সরান এবং একটি অ্যাডমিন অ্যাকাউন্ট শেয়ার করবেন না।

ব্যাকআপ সুরক্ষিত রাখুন

আর্কাইভে গ্রাহকের যোগাযোগের তথ্য ও ব্যবসার রেকর্ড থাকে। কপিগুলো এনক্রিপ্টেড, অ্যাক্সেস-নিয়ন্ত্রিত স্টোরেজে রাখুন এবং প্রয়োজন শেষে মুছে ফেলুন।

হোস্ট সুরক্ষিত করুন

অপারেটিং সিস্টেম ও Docker হালনাগাদ রাখুন, SSH সীমিত করুন এবং শুধু প্রয়োজনীয় পোর্ট খুলুন: SSH, ৮০ ও ৪৪৩। PostgreSQL পাবলিক করবেন না।

আপডেট লক্ষ্য করুন

রিলিজ ও নিরাপত্তা সংশোধনের জন্য রিপোজিটরি দেখুন। আপগ্রেড গাইড পড়ুন, আগে ব্যাকআপ নিন এবং প্রতি আপডেটের পর যাচাই করুন।

সিক্রেট ফাঁস হলে

নতুন মান তৈরি করুন, .env হালনাগাদ করুন এবং স্ট্যাক রিস্টার্ট করুন। JWT_SECRET বদলালে বিদ্যমান অ্যাক্সেস টোকেন অকার্যকর হয়। API_KEY ওয়েব ও API কন্টেইনারে একই থাকতে হবে। ডেটাবেস পাসওয়ার্ড বদলালে PostgreSQL-এর ভেতরেও সেটি বদলাতে হবে, শুধু .env-তে নয়।

নিরাপত্তা সমস্যা গোপনে জানান

নিরাপত্তা সমস্যার জন্য পাবলিক ইস্যু খুলবেন না। রিপোজিটরির নিরাপত্তা নীতি অনুসরণ করে মেইনটেইনারের সঙ্গে গোপনে যোগাযোগ করুন।

VendKit AGPL-3.0 লাইসেন্সে প্রকাশিত। পরিবর্তিত সংস্করণ নেটওয়ার্ক সেবা হিসেবে চালালে লাইসেন্স অনুযায়ী ব্যবহারকারীদের কাছে এর সোর্স কোড দেওয়ার প্রস্তাব করতে হবে।

সমস্যা সমাধান

সাধারণ ব্যর্থতাগুলো ঠিক করুন।

কন্টেইনারের অবস্থা ও API লগ দিয়ে শুরু করুন। VendKit চালুর সময়ই তার এনভায়রনমেন্ট যাচাই করে এবং অনুপস্থিত বা ভুল মান লগে জানায়।

API লগ পড়ুন

কোনো প্রয়োজনীয় ভেরিয়েবল না থাকলে API চালু হতে অস্বীকার করে এবং পাওয়া সব সমস্যার তালিকা দেয়।

টার্মিনাল
docker compose logs --tail=200 api

Compose ফাইল যাচাই করুন

রিবিল্ডের আগে .env আছে কি না এবং Compose ফাইল ঠিকভাবে রিজলভ হয় কি না দেখুন।

টার্মিনাল
docker compose config --quiet

Compose “Set … in .env” বলে থেমে যায়

রুট .env ফাইল নেই বা কোনো প্রয়োজনীয় মান খালি। .env.example থেকে .env তৈরি করুন এবং সিক্রেট আবার জেনারেট করুন।

API কন্টেইনার বারবার রিস্টার্ট হয়

API লগ পড়ুন। DATABASE_URL, JWT_SECRET বা API_KEY না থাকলে, অথবা JWT_SECRET ৩২ অক্ষরের কম হলে API চালু হয় না।

সাইন ইন লুপ করে বা কিছুই করে না

প্রোডাকশন কুকি Secure। সাধারণ HTTP ঠিকানার বদলে HTTPS URL ব্যবহার করুন এবং APP_URL পাবলিক অরিজিনের সঙ্গে মিলছে কি না দেখুন।

ওয়েব অ্যাপ API-তে পৌঁছাতে পারছে না

API সুস্থ কি না দেখুন। Compose-এ NEST_API_URL অবশ্যই http://api:4000/api হবে এবং API_KEY ওয়েব ও API সার্ভিসে একই থাকতে হবে।

৩০০০ পোর্ট ইতিমধ্যে ব্যবহৃত

.env-তে WEB_PORT অন্য পোর্টে দিন, স্ট্যাক রিস্টার্ট করুন এবং রিভার্স প্রক্সির আপস্ট্রিম হালনাগাদ করুন। কন্টেইনার ভেতরে এখনও ৩০০০-ই শোনে।

রিস্টার্টের পর ডেটা হারিয়ে গেছে

সম্ভবত ভলিউমসহ স্ট্যাক সরানো হয়েছে। বাস্তব ইনস্টলেশনে কখনো docker compose down --volumes ব্যবহার করবেন না। সর্বশেষ ব্যাকআপ রিস্টোর করুন এবং দুটি নামযুক্ত ভলিউম রাখুন।

রিস্টোর প্রত্যাখ্যাত হচ্ছে

ম্যানিফেস্টের সংস্করণ চলমান অ্যাপের সঙ্গে মিলতে হবে এবং প্রতিটি চেকসাম ও মিডিয়ার আকার যাচাই হতে হবে। যে আর্কাইভের ফরম্যাট চলমান অ্যাপের সঙ্গে মেলে সেটি ব্যবহার করুন এবং কারণ ব্যাকআপ ইতিহাসে দেখুন।

বিল্ড ব্যর্থ বা অ্যাপ ধীর

df -h দিয়ে খালি ডিস্ক এবং docker system df দিয়ে Docker ব্যবহার দেখুন। বর্তমান ব্যাকআপ থাকলে তবেই অব্যবহৃত ইমেজ ও বিল্ড ক্যাশ পরিষ্কার করুন।

ভলিউম, পোর্ট বা এনভায়রনমেন্ট মান বদলানোর আগে নতুন ব্যাকআপ ডাউনলোড করুন। কীভাবে রিস্টোর করবেন তা ব্যাখ্যা করতে না পারলে চালু দোকানে সেই পরিবর্তন করবেন না।

আর্কিটেকচার

এক ওয়েব অ্যাপ, এক API, এক ডেটাবেস

ব্রাউজার শুধু Next.js অ্যাপের সঙ্গে কথা বলে। সার্ভারের ভেতরের রুট হ্যান্ডলার শেয়ার্ড API কী দিয়ে NestJS-এ অনুরোধ পাঠায়, তাই API পাবলিকভাবে খোলা রাখতে হয় না।

রিপোজিটরি

  • apps/web

    Next.js ফ্রন্টএন্ড ও সার্ভার-সাইড API প্রক্সি।

  • apps/api

    NestJS API, ব্যবসার লজিক, ইনভয়েস PDF ও ব্যাকআপ।

  • packages/database

    Prisma স্কিমা, মাইগ্রেশন ও জেনারেট করা ক্লায়েন্ট।

  • packages/ui

    অ্যাপ্লিকেশনের শেয়ার্ড UI উপাদান।

  • docker-compose.yml

    ওয়েব, API ও PostgreSQL—ডেটা ও আপলোডের জন্য স্থায়ী ভলিউমসহ।

রেফারেন্স

রিপোজিটরিই নির্ভরযোগ্য সূত্র

এই লিংকগুলো VendKit রিপোজিটরিতে নিয়ে যাবে। সেগুলো এই সাইটের সঙ্গে নয়, অ্যাপ্লিকেশনের সঙ্গে আপডেট হয়।