👨‍💻 تثبيت LocalStack — تشغيل خدمات AWS محلياً

انشر LocalStack على Ubuntu بـ Docker — محاكي سحابة AWS محلي يشغّل S3 وLambda وDynamoDB وSQS وغيرها على جهازك الخاص حتى تطوّر وتختبر بدون حساب AWS.

⚠️ راجع أي سكريبت دائمًا قبل تشغيله على سيرفرك، واختبره في بيئة تجريبية أولاً.

📦 الملفات والأكواد المطلوبة

قبل البدء، يرجى التأكد من تحميل الأكواد المطلوبة من مستودعنا على GitHub لتتمكن من تطبيق الخطوات مع الفيديو بسهولة.

سكريبت تثبيت آلي — أمر واحد ينشر LocalStack على منفذ edge رقم 4566 مع تفعيل الحفظ الدائم للبيانات.
عرض على GitHub

التثبيت السريع:

wget https://raw.githubusercontent.com/mhmdali94/Docker/main/dev/localstack/localstack-ubuntu.sh
chmod +x localstack-ubuntu.sh
sudo bash localstack-ubuntu.sh

خطوات التنفيذ

1 تحميل السكريبت

wget https://raw.githubusercontent.com/mhmdali94/Docker/main/dev/localstack/localstack-ubuntu.sh

2 منحه صلاحية التنفيذ

chmod +x localstack-ubuntu.sh

3 تشغيل المثبّت

يثبّت السكريبت Docker إن لزم الأمر، يسحب صورة localstack/localstack، ويشغّلها على منفذ edge رقم 4566 مع تفعيل PERSISTENCE وربط Docker socket حتى تستطيع Lambda إنشاء حاويات تشغيل خاصة بها.

sudo bash localstack-ubuntu.sh

4 الاختبار باستخدام AWS CLI

لا تملك LocalStack واجهة ويب في النسخة المجانية. وجّه أوامر AWS CLI نحو نقطة edge لإنشاء دلو S3 تجريبي:

aws --endpoint-url=http://<your-server-ip>:4566 s3 mb s3://test

المنافذ المستخدمة

المنفذالغرض
4566Edge endpoint — every emulated AWS service
docker.sockMounted so Lambda can start runtime containers

نظرة عامة

LocalStack محاكي خدمات سحابية مفتوح المصدر يشغّل جزءاً كبيراً من واجهات AWS البرمجية — S3 وLambda وDynamoDB وSQS وSNS وAPI Gateway وعشرات الخدمات الأخرى — داخل حاوية Docker واحدة على جهازك الخاص. بدلاً من تجهيز موارد AWS حقيقية لكل اختبار، توجّه استدعاءات AWS SDK أو CLI الموجودة لديك نحو نقطة نهاية محلية وتحصل على سلوك واقعي دون حساب AWS ودون تكاليف سحابية ودون اتصال بالإنترنت. تغطي النسخة المجانية Community أكثر الخدمات استخداماً وهي كافية لمعظم عمليات التطوير المحلي واختبار CI؛ بينما تضيف نسخة Pro المدفوعة خدمات أكثر ولوحة تحكم وميزات متقدمة.

لماذا تستخدمه

يتيح لك LocalStack بناء واختبار تطبيقات تعتمد على AWS بشكل كامل دون اتصال بالإنترنت، دون تجهيز موارد سحابية حقيقية أو الدفع مقابل الاستخدام أثناء التطوير. ولأنه يطبّق نفس واجهات AWS البرمجية، يعمل كود SDK وإعدادات Terraform وسكريبتات CLI الموجودة لديك معه بمجرد تغيير نقطة النهاية فقط — دون أي تعديل في كود التطبيق. هذا يجعله مثالياً للتكرار السريع محلياً، واختبارات التكامل التي تنشئ وتحذف بنية تحتية بشكل متكرر، وخطوط CI التي تحتاج سلوكاً شبيهاً بـ AWS دون بيانات اعتماد حقيقية أو وصول شبكي لـ AWS.

متى تحتاجه

  • تبني تطبيقاً يعتمد على خدمات AWS (S3، Lambda، DynamoDB، SQS) وتريد التطوير دون حساب AWS حقيقي
  • تريد اختبارات تكامل تنشئ وتحذف موارد AWS في كل تشغيل دون تحمل تكاليف سحابية أو الاصطدام بحدود المعدل
  • تحتاج خط CI يختبر كوداً يعتمد على AWS دون تخزين بيانات اعتماد AWS حقيقية في خط الأنابيب
  • تريد تجربة دوال Lambda بدون خادم محلياً قبل نشرها على حساب AWS حقيقي
  • تُدرّس أو تتعلم خدمات AWS وتريد بيئة تجريبية مجانية تتصرف كالنسخة الحقيقية
  • تحتاج اختبار تغييرات في Terraform أو CloudFormation كبنية تحتية ككود دون تجهيز بنية تحتية حقيقية

من يحتاجه

  • مطورو الخلفية الذين يبنون تطبيقات على خدمات AWS ويريدون حلقة تغذية راجعة محلية سريعة
  • مهندسو DevOps والمنصات الذين يحتاجون التحقق من قوالب Terraform أو CloudFormation قبل تطبيقها على الإنتاج
  • مهندسو ضمان الجودة وأتمتة الاختبار الذين يحتاجون بيئات AWS معزولة وقابلة للتكرار لاختبارات التكامل
  • الفرق التي تُشغّل خطوط CI/CD تختبر كوداً يعتمد على AWS مع كل تعديل دون بيانات اعتماد سحابية حقيقية
  • الطلاب والمدربون الذين يتعلمون خدمات AWS ولا يريدون المخاطرة برسوم غير متوقعة على حساب حقيقي
  • الاستشاريون والمستقلون الذين يحتاجون عرض بنى معمارية قائمة على AWS دون تجهيز موارد سحابية للعميل

حالات الاستخدام الشائعة

  • تطوير واختبار منطق رفع وتنزيل الملفات عبر S3 محلياً قبل توجيه نفس الكود لـ S3 الحقيقي
  • كتابة وتصحيح دوال Lambda محلياً بتكرار سريع بدلاً من دورة نشر-اختبار على AWS الحقيقي
  • تشغيل اختبارات تكامل ضد DynamoDB وSQS وSNS في خطوط CI دون لمس حساب AWS حقيقي
  • التحقق من خطط Terraform وحزم CloudFormation ضد المحاكي المحلي قبل تطبيقها على الإنتاج
  • محاكاة واجهات API Gateway المدعومة بـ Lambda لتطوير الواجهة الأمامية دون انتظار نشر الخلفية السحابية
  • إعادة إنتاج وتصحيح مشكلات إنتاج متعلقة بـ AWS في بيئة محلية قابلة للتخلص منها

الميزات الرئيسية

  • يحاكي مجموعة واسعة من خدمات AWS الأساسية — S3 وLambda وDynamoDB وSQS وSNS وAPI Gateway وIAM وCloudFormation وغيرها
  • نقطة نهاية edge واحدة على المنفذ 4566 توجّه الطلبات للخدمة المحاكاة الصحيحة، بنفس طريقة عنونة AWS SDK للخدمات
  • يعمل مع AWS CLI القياسي وجميع حزم AWS SDK الرسمية — يتغير فقط عنوان نقطة النهاية، ويبقى كود التطبيق كما هو
  • حفظ بيانات اختياري بحيث تبقى الموارد المحاكاة (الدلاء، الجداول، الطوابير) بعد إعادة تشغيل الحاوية
  • دعم Docker-in-Docker لـ Lambda، بإنشاء حاوية تشغيل حقيقية لكل استدعاء دالة لسلوك دقيق
  • متوافق مع أدوات البنية التحتية ككود مثل Terraform وAWS CDK وCloudFormation عبر نقطة النهاية المحلية
  • لا يحتاج حساب AWS حقيقي أو بيانات اعتماد — يُقبل أي مفتاح وصول وسر وهمي
  • نسخة Pro المدفوعة تضيف لوحة تحكم ويب وخدمات أكثر وميزات متقدمة مثل تطبيق سياسات IAM

كيفية الاستخدام بعد التثبيت

  • اضبط AWS CLI بأي بيانات اعتماد وهمية — لا يتحقق منها LocalStack: aws configure set aws_access_key_id test
  • وجّه كل أمر AWS CLI نحو نقطة نهاية edge باستخدام --endpoint-url=http://your-server-ip:4566
  • أنشئ أول مورد تجريبي، مثلاً دلو S3: aws --endpoint-url=http://your-server-ip:4566 s3 mb s3://test
  • استخدم AWS SDK في تطبيقك بضبط معامل نقطة نهاية مخصص إلى نفس رابط edge بدلاً من نقطة نهاية AWS الحقيقية
  • للاختبار المحلي المتكرر، فكّر في تثبيت سكريبت awslocal الذي يوجّه تلقائياً نحو نقطة نهاية LocalStack
  • انشر واستدعِ دالة Lambda تجريبية للتأكد من عمل ربط Docker socket وقدرة حاويات التشغيل على البدء
  • استخدم Terraform أو AWS CDK ضد نقطة النهاية المحلية للتحقق من تغييرات البنية التحتية قبل تطبيقها على AWS الحقيقي
  • راجع سجلات الحاوية بـ docker logs إذا تصرفت خدمة ما بشكل غير متوقع — يسجّل LocalStack استدعاءات AWS API التي استقبلها

أفضل ممارسات الأمان

  • لا تكشف المنفذ 4566 للإنترنت العام أبداً — لا يقوم LocalStack بأي مصادقة حقيقية ويقبل أي بيانات اعتماد بحكم تصميمه
  • شغّل LocalStack فقط على جهاز تطوير محلي أو أداة تشغيل CI معزولة أو شبكة داخلية خاصة، وليس كخدمة عامة على الإنترنت
  • قيّد الوصول لمنفذ edge بجدار حماية إذا كان يعمل على سيرفر مشترك، مع السماح فقط لأجهزة المطورين الموثوقة أو أدوات تشغيل CI
  • انتبه إلى أن ربط Docker socket يمنح حاوية LocalStack تحكماً كبيراً في محرك Docker على المضيف — شغّله فقط على مضيفين موثوقين
  • لا تخزّن بيانات اعتماد AWS حقيقية في نفس البيئة أو الإعدادات المستخدمة مع اختبار LocalStack لتفادي إصابة AWS الإنتاجي عن طريق الخطأ
  • حدّث صورة LocalStack Docker باستمرار للحصول على إصلاحات أمنية وتوافقية للخدمات المحاكاة
  • تعامل مع أي بيانات مخزّنة في LocalStack كبيانات اختبار قابلة للتخلص منها — فهو ليس مصمماً أو مُحصّناً كمخزن بيانات إنتاجي

المنافذ وإعدادات جدار الحماية

يكشف LocalStack منفذاً واحداً فقط، edge على 4566، تُتاح من خلاله جميع خدمات AWS المحاكاة — لا حاجة لفتح منافذ منفصلة لكل خدمة كما قد تفعل مع قواعد بيانات أو تطبيقات فردية. تحتاج الحاوية أيضاً وصولاً إلى Docker socket الخاص بالمضيف (عادة مربوط على /var/run/docker.sock) حتى تستطيع استدعاءات Lambda إنشاء حاويات تشغيل خاصة بها؛ هذا ربط محلي وليس منفذ شبكة، ولا يحتاج أي قاعدة جدار حماية. ولأن LocalStack يقبل أي بيانات اعتماد ولا يجري مصادقة حقيقية، يجب ألا يُكشف المنفذ 4566 للإنترنت أبداً — أبقه مرتبطاً بالمضيف المحلي أو شبكة خاصة، وإذا كان الوصول عن بُعد ضرورياً فعلاً، قيّده بعناوين IP موثوقة أو VPN بدلاً من فتحه للعامة.

النسخ الاحتياطي والصيانة

  • إذا كان PERSISTENCE مفعّلاً، انسخ احتياطياً دليل بيانات LocalStack الذي يخزّن حالة الموارد المحاكاة (كائنات S3، جداول DynamoDB، الطوابير)
  • انسخ docker-compose.yml أو أمر docker run الخاص بك حتى يمكن إعادة إنشاء نفس الإعدادات وإعدادات الحفظ الدائم
  • بما أن LocalStack أداة تطوير واختبار، تتعامل معظم الفرق مع بياناته كبيانات قابلة للتخلص منها وتعيد إنشاءها بدلاً من استعادة النسخ الاحتياطية
  • احفظ في نظام التحكم بالإصدارات ملفات Terraform وCloudFormation أو سكريبتات الإعداد التي تجهّز الموارد داخل LocalStack، حتى يمكن إعادة بناء البيئة من الصفر في أي وقت
  • اسحب أحدث صورة LocalStack دورياً لمواكبة خدمات AWS المحاكاة الجديدة وإصلاحات الأخطاء
  • وثّق أي متغيرات بيئة أو إعدادات خدمات مخصصة حتى يمكن لأي عضو في الفريق إعادة إنشاء نسخة جديدة بسرعة

الأخطاء الشائعة

  • نسيان علامة --endpoint-url في أوامر AWS CLI، مما يجعل CLI يتحدث بصمت مع AWS الحقيقي بدلاً من LocalStack
  • كشف المنفذ 4566 للإنترنت العام، مع نسيان أن LocalStack لا يملك مصادقة حقيقية وسيقبل أي طلب
  • عدم ربط Docker socket، ثم التساؤل عن سبب فشل استدعاءات Lambda بينما تعمل خدمات أخرى مثل S3 بشكل طبيعي
  • افتراض أن كل خدمة AWS وكل عملية API مُحاكاة بالكامل — التغطية واسعة لكنها ليست كاملة 100%، خاصة لميزات AWS الأحدث أو النادرة
  • خلط بيانات اعتماد AWS حقيقية في سكريبتات تُستخدم أيضاً ضد LocalStack، مما يخاطر باستدعاء AWS الإنتاجي عن طريق الخطأ
  • عدم تفعيل PERSISTENCE ثم فقدان كل بيانات الاختبار مع كل إعادة تشغيل للحاوية
  • توقّع لوحة تحكم ويب في النسخة المجانية Community — اللوحة وبعض الخدمات جزء من نسخة Pro المدفوعة

استكشاف الأخطاء وإصلاحها

  • أوامر AWS CLI تصل إلى AWS الحقيقي بدلاً من LocalStack — تأكد من ضبط علامة --endpoint-url في كل أمر أو استخدم سكريبت awslocal
  • استدعاءات Lambda تفشل فوراً — تأكد من ربط Docker socket داخل الحاوية وأن مستخدم المضيف يملك صلاحية الوصول إليه
  • الاتصال مرفوض على المنفذ 4566 — تحقق من تشغيل الحاوية بـ docker ps ومن عدم حظر الوصول المحلي بجدار حماية
  • البيانات تختفي بعد كل إعادة تشغيل — تأكد من ضبط متغير البيئة PERSISTENCE على 1 ومن ربط حجم لدليل البيانات
  • خدمة AWS معينة تتصرف بشكل مختلف عن AWS الحقيقي — راجع توثيق LocalStack لمعرفة القيود المعروفة لتلك الخدمة في نسخة Community
  • فشل Terraform apply ضد نقطة النهاية المحلية — تأكد من ضبط بلوك المزود بنقاط النهاية الصحيحة لكل خدمة وتفعيل skip_credentials_validation
  • أداء بطيء مع موارد كثيرة — يشغّل LocalStack كل شيء في حاوية واحدة، لذا قد تستفيد مجموعة اختبارات كثيفة من تخصيص المزيد من CPU والذاكرة لـ Docker

البدائل

يركّز AWS SAM Local (جزء من AWS Serverless Application Model CLI) بشكل ضيق على تشغيل واختبار دوال Lambda وAPI Gateway محلياً، دون محاكاة النطاق الأوسع لخدمات AWS التي يغطيها LocalStack. MinIO خادم تخزين كائنات خفيف متوافق مع S3 — خيار جيد إذا كنت تحتاج فقط محاكاة S3 ولا شيء آخر. Moto مكتبة Python تحاكي خدمات AWS على مستوى الكود لاختبارات الوحدة، مفيدة لمجموعات اختبار Python البحتة لكنها ليست خدمة مستقلة مثل LocalStack. DynamoDB Local، المقدمة مباشرة من AWS، تحاكي DynamoDB فقط وهي بديل ضيق قوي إذا كانت اعتمادك الوحيد. للفرق التي تحتاج محاكاة واسعة متعددة الخدمات لـ AWS خلف نقطة نهاية واحدة مع توافق حقيقي مع SDK وCLI، يبقى LocalStack الخيار الأكثر اكتمالاً.

متى لا تستخدمه

LocalStack ليس خدمة إنتاجية — إنه أداة تطوير واختبار، ويجب ألا تُستخدم خدماته المحاكاة أبداً لتخزين بيانات إنتاجية حقيقية. إذا كان فريقك يعتمد فقط على خدمة أو خدمتين بسيطتين من AWS، يمكن أن تكون أداة أضيق مثل MinIO (لـ S3) أو DynamoDB Local أخف وأبسط تشغيلاً من حاوية LocalStack الكاملة. تغطية المحاكاة، رغم اتساعها، لا تطابق دائماً سلوك AWS الحقيقي بشكل مثالي في كل حالة حدّية — للتحقق النهائي قبل إصدار كبير، يبقى الاختبار ضد حساب AWS تجريبي حقيقي مفيداً. إذا كنت تحتاج الميزات المتقدمة المحددة أو خدمات محاكاة إضافية أو لوحة التحكم الويب المحجوبة خلف نسخة Pro المدفوعة، ستحتاج لموازنة تلك التكلفة مع احتياجات فريقك.

هل تحتاج مساعدة احترافية؟

توفر PrismaTechWork خدمات بنية تحتية شاملة — من النشر الأولي وتصليب الأمان إلى المراقبة المستمرة والنسخ الاحتياطي التلقائي والدعم المخصص. سواء كنت تحتاج إعداد سيرفر واحد أو شبكة متعددة المواقع، يضمن فريقنا بناء بنيتك التحتية بشكل صحيح وتأمينها بالشكل المناسب وصيانتها باستمرار.

  • التثبيت وتجهيز السيرفر
  • الإعداد المتقدم وإعداد التوجيه
  • تصليب الأمان وتحسين جدار الحماية
  • إعداد شهادات SSL/TLS مع Let's Encrypt
  • ربط النطاق المخصص والوكيل العكسي
  • جدولة النسخ الاحتياطي التلقائي والتعافي من الكوارث
  • المراقبة الفورية وتنبيهات الجاهزية
  • الترحيل من المنصات القائمة
  • استكشاف مشكلات الاتصال والأداء وإصلاحها
  • سكريبتات أتمتة مخصصة وعقود دعم مستمر
تواصل مع PrismaTechWork

الأسئلة الشائعة

ما استخدام LocalStack؟

يحاكي LocalStack خدمات AWS محلياً داخل حاوية Docker، حتى تطوّر وتختبر ضد S3 وLambda وDynamoDB وSQS وغيرها دون حساب AWS. يبقى كودك واستدعاءات SDK كما هي — يتغير فقط عنوان نقطة النهاية ليشير إلى LocalStack بدلاً من AWS الحقيقي.

كيف أوجّه AWS CLI نحو LocalStack؟

أضف علامة --endpoint-url، مثلاً: aws --endpoint-url=http://your-server-ip:4566 s3 mb s3://test. نسيان هذه العلامة هو الخطأ الأكثر شيوعاً — بدونها يتحدث CLI مع AWS الحقيقي. يقبل LocalStack أي بيانات اعتماد وهمية لأنه لا يتحقق من مفاتيح AWS الحقيقية.

ما المنفذ الذي يستخدمه LocalStack؟

منفذ واحد فقط: edge على 4566. تُتاح كل خدمة محاكاة عبر نقطة النهاية الواحدة تلك بدلاً من منافذ منفصلة لكل خدمة. لا تكشف المنفذ 4566 للإنترنت أبداً، لأن LocalStack لا يجري مصادقة حقيقية ويقبل أي بيانات اعتماد.

هل يملك LocalStack واجهة ويب؟

النسخة المجانية Community مبنية على API فقط — تتفاعل معها عبر AWS CLI أو SDK. لوحة تحكم LocalStack الويب والخدمات الإضافية جزء من عرض Pro المدفوع. لمعظم أعمال التطوير المحلي واختبار CI، النسخة المجانية القائمة على API كافية.

لماذا يحتاج LocalStack إلى Docker socket؟

لأن Lambda تنفّذ كل دالة داخل حاوية خاصة بها. يتحدث LocalStack مع محرك Docker عبر socket المربوط لإنشاء حاويات التشغيل تلك. إذا لم يُربط socket، ستفشل استدعاءات Lambda بينما تستمر خدمات أخرى مثل S3 بالعمل.