التثبيت باستخدام Docker Compose

‏Docker Compose هو طريقة تشغيل Kept على جهاز واحد: Kept نفسه، وPostgres 18 مع pgvector، وإن شئت Caddy من أجل HTTPS. تحتاج إلى Docker مع إضافة Compose، وإلى جهاز بذاكرة ٢ غيغابايت على الأقل ونواتَي معالجة (ما يحتاجه).

تبنيها أو تسحبها

تُنشر الإصدارات على ghcr.io/keptinventory/kept بالوسوم 1 و1.2 و1.2.3، ولا يوجد latest أبدًا، والإصدار 1.0.0 أول إصدار موقَّع. ومن دون KEPT_IMAGE يبني compose.yaml الصورة من نسخة من المستودع ويوسمها kept:local. ولتشغيل إصدار بدلًا من ذلك، اضبط KEPT_IMAGE في .env على وسم إصدار ثم نفّذ docker compose pull، بعد أن تتحقق منه.

١. املأ ملف ‎.env‎

انسخ المثال بجانب compose.yaml واملأه. لا يُرفع .env إلى أي مكان.

cp compose.env.example .env

• خمس كلمات مرور لقاعدة البيانات (KEPT_DB_SUPERUSER_PASSWORD وKEPT_DB_OWNER_PASSWORD وKEPT_DB_APP_PASSWORD وKEPT_DB_AUTH_PASSWORD وKEPT_DB_SYSTEM_PASSWORD). ولّد كل واحدة، مثلًا بالأمر openssl rand -hex 32؛ فالصيغة الست عشرية لا تحتاج إلى تهريب داخل عناوين قاعدة البيانات التي يبنيها Compose. تُقرأ مرة واحدة عند إنشاء مجلد قاعدة البيانات أول مرة، وتغيير إحداها لاحقًا يتطلب أيضًا ALTER ROLE … PASSWORD في psql.
• ‏KEPT_PUBLIC_URL: العنوان الذي يفتحه الناس، مثل https://kept.example.org. منه تُبنى الروابط ورموز QR والتحقق من المصدر، فيجب أن يطابق تمامًا ما يظهر في المتصفح.

كل ما عدا ذلك اختياري؛ تشرح التعليقات في compose.env.example ومرجع الإعدادات عمل كل متغير.

٢. شغّله

docker compose up -d

يبدأ Compose قاعدة البيانات وينتظر جاهزيتها، ثم يشغّل خدمة migrate لمرة واحدة (kept migrate، الذي يطبّق تحديثات مخطط قاعدة البيانات مرة واحدة تحت قفل)، ثم يشغّل Kept على المنفذ 8080 (يغيّر KEPT_HTTP_PORT منفذ الجهاز). وفي أول تشغيل، ينشئ سكربت التهيئة حسابات الدخول الأربعة لقاعدة البيانات والإضافات pg_trgm وunaccent وvector.

٣. أكمل الإعداد

يطبع Kept رمز إعداد يُستخدم مرة واحدة حين يبدأ بلا مدير:

docker compose logs kept | grep "KEPT SETUP CODE"

افتح KEPT_PUBLIC_URL وأدخل الرمز وأنشئ الحساب الأول: يصبح مدير النسخة. ولتحديد الرمز مسبقًا، اضبط KEPT_SETUP_CODE في .env (ستة محارف من 0–9 وA–Z بلا I وL وO وU). ويُصدَر الرمز المفقود من جديد بالأمر:

docker compose run --rm migrate admin setup-code

الرموز الخاطئة تقفل الإعداد مدةً، لكل عنوان وللنسخة كلها. وإن كان Kept خلف وكيل لا يثق به، يتشارك الجميع عنوان الوكيل؛ راجع الوكلاء العكسيين.

٤. احفظ المفاتيح

في أول تشغيل، ومع ترك KEPT_SECRET_KEY وKEPT_AUTH_SECRET فارغين، يولّدهما Kept في مجلد kept-config ويكتب سطرًا واحدًا في السجل يقول أين. المفتاح السري يختم كل قيمة سرية (مفاتيح الذكاء الاصطناعي وكلمات المرور التي تحفظها في Kept): النسخة الاحتياطية تستعيد كل شيء ما عدا هذه القيم إن لم يكن المفتاح معك.

اطبع المفاتيح واحفظها في مكان غير هذا الخادم، كمدير كلمات مرور:

docker compose exec kept kept admin recovery-kit

تطلب صفحة الإدارة ← الحالة إقرارك بحزمة الاسترداد، ويشترطه Kept قبل أول قيمة سرية أو مفتاح ذكاء اصطناعي أو إعداد نسخ احتياطي. راجع حزمة الاسترداد.

٥. بعد ذلك

• شغّل Kept عبر HTTPS: الكاميرا وتثبيت التطبيق والإشعارات والموقع لا تعمل إلا عبر HTTPS.
• أعدّ النسخ الاحتياطي.
• البريد: اضبط KEPT_SMTP_URL (‏smtp:// أو smtps:// مع بيانات الدخول) وKEPT_SMTP_FROM من أجل استعادة كلمات المرور والدعوات والتذكيرات بالبريد. وبدونهما تصل التذكيرات داخل التطبيق فقط، وتقول صفحة الإدارة ← الحالة إن البريد غير مُعَدّ.

ما ينشئه Compose

المجلد	ما فيه	انسخه احتياطيًا؟
kept-db	قاعدة بيانات Postgres	عبر النسخ الاحتياطي في Kept، ولا تنسخ المجلد أثناء التشغيل أبدًا
kept-data	الملفات المرفوعة (مع KEPT_STORAGE=local، الافتراضي)	عبر النسخ الاحتياطي في Kept
kept-config	‏KEPT_SECRET_KEY وKEPT_AUTH_SECRET المولَّدان فقط	احفظ حزمة الاسترداد بدلًا منه
caddy-data وcaddy-config	شهادات Caddy (ملف التعريف https)	لا؛ يحصل Caddy على شهادات جديدة

تعمل حاويات Kept بمستخدم غير جذري (uid 10001)، بنظام ملفات جذري للقراءة فقط، مع إسقاط كل صلاحيات لينكس وno-new-privileges. تحمل خدمة migrate حساب مالك قاعدة البيانات، ولا تحمله الحاوية التي تخدم الطلبات أبدًا.