ساخت سیارات با Perlanet و GitHub

دورتر در پس‌آب‌های ناشناخته انتهای نامتعارف بازوی مارپیچی غربی کهکشان، خورشید کوچک زرد و نادیده گرفته‌ای قرار دارد. چرخش به دور این سیاره در فاصله تقریباً نود و دو میلیون مایلی، یک سیاره سبز آبی کوچک کاملاً ناچیز است که شکل‌های حیاتی که از میمون‌ها فرود آمده‌اند آنقدر ابتدایی هستند که هنوز فکر می‌کنند ساعت‌های دیجیتال ایده‌ای بسیار زیبا هستند.

داگلاس آدامز – راهنمای سفر به کهکشان

من هنوز ساعت دیجیتال نمی پوشم، اما چیزهای دیگری را که تقریباً به همان اندازه بی ران هستند دوست دارم. به طور خاص، من برای زمان حدود بیست سال پیش که فیدهای وب به نظر می‌رسیدند که در شرف تصرف جهان هستند، نگران هستم. همه فیدخوان مورد علاقه خود را داشتند (هنوز دلم برای Google Reader تنگ شده است) و تقریباً هر وب سایت مفیدی یک یا چند فید وب تولید می کند که می توانید مشترک شوید و از طریق فیدخوان خود دنبال کنید. برای چند سال، تقریبا غیرقابل تصور بود که یک وب سایت بدون انتشار فید که شامل تغییرات در محتوای سایت باشد، تولید کرد.

سپس، در یک نقطه، این تغییر کرد. اینطور نبود که فیدهای وب یک شبه ناپدید شوند. آنها هنوز برای بسیاری از سایت ها وجود دارند. اما آنها دیگر در همه جا حاضر نیستند. شما نمی توانید تضمین کنید که آنها برای هر سایتی که به آن علاقه دارید وجود خواهد داشت. من به یاد دارم که مردم می گفتند که رسانه های اجتماعی جایگزین آنها می شوند. من هرگز با این استدلال قانع نشدم، اما جالب است که یکی از اولین بارهایی که متوجه ناپدید شدن آنها شدم زمانی بود که توییتر فید وب پست های یک کاربر را حذف کرد. آنها از مردم می خواستند که به جای آن از AP ​​خود استفاده کنند (بنابراین من در twitter-json2atom نوشتم که JSON API آنها را به یک فید Atom تبدیل کرد – من گمان می کنم که دیگر کار نمی کند). صادقانه بگویم، من فکر می کنم دلیل اصلی کاهش محبوبیت فیدهای وب این بود که مردم از شما می خواستند محتوای آنها را در وب سایت هایشان بخوانید، جایی که محتوای جالب با تبلیغات غیر جالب احاطه شده بود.

اما، همانطور که گفتم، همه فیدهای وب ناپدید نشدند. هنوز تعداد زیادی از آنها وجود دارد (اغلب، من انتظار دارم زیرا صاحبان سایت ها متوجه وجود آنها نمی شوند یا نمی دانند چگونه آنها را خاموش کنند). و این بدان معناست که فناوری‌های فید محور اوایل دهه 2000 هنوز هم می‌توانند مفید باشند.

یکی از این فناوری‌ها، جمع‌کننده خوراک است. من به یاد دارم که اینها بسیار محبوب بودند. شما یک وب‌سایت ایجاد می‌کنید و آن را با فهرستی از فیدهای وب که به آن‌ها علاقه‌مند بودید پیکربندی می‌کنید. سایت توسط یک نرم‌افزار هدایت می‌شود که هر چند ساعت یکبار فیدهای وب را در پیکربندی نظرسنجی می‌کند و از اطلاعاتی که پیدا کرده است استفاده می‌کند. الف) یک صفحه وب متشکل از اطلاعات فیدها و ب) فید دیگری که حاوی تمام اطلاعات فیدهای منبع است ایجاد کنید. محبوب ترین نرم افزار برای ساخت این سایت ها Planet Planet نام داشت و به زبان پایتون نوشته شده بود (به نظر می رسد در بیست سال گذشته ناپدید شده است وگرنه به آن لینک می دهم). وقتی نسخه پرل را نوشتم، آن را (به دلایلی که اکنون پشیمان هستم) Perlanet نامیدم.

من هنوز از Perlanet برای ساخت سایت های سیاره ای استفاده می کنم. و همه آنها در The Planetarium فهرست شده اند. اخیراً، من شروع به میزبانی تمام سیارات خود در صفحات GitHub کرده ام و از GitHub Actions برای بازسازی سایت ها به صورت دوره ای استفاده می کنم. من فکر کردم که ممکن است افراد دیگر مانند من قدیمی باشند و ممکن است بخواهند سیاره های خود را بسازند – بنابراین در ادامه این پست نحوه انجام این کار را با استفاده از Planet Perl به عنوان مثال توضیح خواهم داد.

اولین چیزی که به آن نیاز دارید یک حساب GitHub و یک مخزن برای ذخیره کد سیاره شما است. من فرض می کنم که شما می دانید چگونه آنها را تنظیم کنید (به منظور کوتاه نگه داشتن این آموزش). برای ایجاد یک سیاره فقط به دو فایل نیاز دارید – یک فایل پیکربندی و یک الگو برای وب سایت.

در اینجا بخشی از پیکربندی برای Planet Perl آمده است:

title: Planet Perl
description: There's More Than One Way To Aggregate It
url: https://perl.theplanetarium.org/
author:
  name: Dave Cross
  email: dave@theplanetarium.org
  twitter: davorg
entries: 75
entries_per_feed: 5
opml_file: docs/opml.xml
page:
  file: docs/index.html
  template: index.tt
feed:
  file: docs/atom.xml
  format: Atom
google_ga: G-HD966GMRYP
cutoff_duration:
  months: 1
feeds:
  - feed: https://www.perl.com/article/index.xml
    title: perl.com
    web: https://perl.com/
  - feed: https://news.perlfoundation.org/atom.xml
    title: Perl Foundation News
    web: https://news.perlfoundation.org/

من سعی کردم آن را به خودی خود توضیح دهم. در بالا، گزینه های پیکربندی مختلفی برای خروجی (صفحه وب و فید انبوه) وجود دارد و در زیر، جزئیات فیدهایی که می خواهید جمع آوری کنید وجود دارد. ابتدا به گزینه های خروجی نگاه می کنیم.

• عنوان و توضیحات: هر دو رشته هایی هستند که می توانید در صفحه وب ایجاد شده قرار دهید. آنها همچنین در خوراک کل تولید شده استفاده می شوند
• url: اینجا جایی است که صفحه وب در وب در دسترس خواهد بود
• نویسنده: این شامل جزئیات شخصی است که سایت و فید انبوه را منتشر می کند. دسته توییتر اختیاری است
• ورودی ها: حداکثر تعداد ورودی هایی است که خروجی شما در کل شامل می شود
• entries_per_feed: حداکثر تعداد ورودی هایی است که از هر یک از فیدهای خود استفاده خواهید کرد. این برای جلوگیری از غرق شدن خروجی شما با ورودی های یک فید مخصوصاً شلوغ است. این را می توان حذف کرد، در این صورت محدودیتی وجود نخواهد داشت
• opml_file: OPML مخفف “Outline Processor Markup File” است. انتشار یک فایل OPML که یک فایل داده قابل خواندن توسط ماشین است که حاوی لیستی از فیدهایی است که شما در حال جمع آوری هستید، مرسوم بود. این روزها هیچ کس اهمیت نمی دهد. اگر این تنظیم را حذف کنید، فایل ایجاد نخواهد شد.
• صفحه: این شامل جزئیات صفحه وب است که شما ایجاد می کنید. قالب نام فایل قالبی است که برای ایجاد صفحه HTML استفاده می شود (در ادامه در مورد آن بیشتر توضیح می دهیم) و فایل جایی است که صفحه خروجی نوشته می شود. اگر مقدار استفاده شده در مثال من را حفظ کنید، همانطور که بعدا خواهیم دید همه چیز با صفحات GitHub به خوبی کار خواهد کرد.
• خوراک: این شامل جزئیات فید انبوهی است که ما ایجاد می کنیم. می توانید فرمت (Atom یا RSS) و نام فایل را انتخاب کنید. باز هم، نام فایل پیش فرض با صفحات GitHub به خوبی کار می کند
• google_ga: اگر این مقدار وجود داشته باشد، از آن به عنوان شناسه Google Analytics برای صفحه وب ایجاد شده استفاده می شود.
• cutoff_duration: این روش دیگری برای کنترل ورودی هایی است که در فید خروجی شما استفاده می شود. هر ورودی که بیشتر از این بازه زمانی منتشر شده باشد نادیده گرفته خواهد شد

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

• خوراک: نشانی اینترنتی فید
• عنوان: رشته ای برای توصیف فید
• وب: URL صفحه وب اصلی فید

و این تنها چیزی است که برای فایل پیکربندی نیاز دارید. آن را ایجاد کنید، آن را در فایلی به نام “perlanetrc” قرار دهید و به مخزن خود اضافه کنید.

فایل دیگری که نیاز دارید الگوی صفحه HTML است. این معمولا “index.tt” نامیده می شود. موردی که من برای Planet Perl استفاده می کنم بسیار پیچیده است (انواع ترفندهای جاوا اسکریپت در آن وجود دارد). موردی که من برای Planet Davorg استفاده می کنم بسیار ساده تر است – و باید با فایل پیکربندی بالا به خوبی کار کند. من پیشنهاد می‌کنم در ابتدا آن را دنبال کنید و زمانی که همه چیز کار کرد، آن را ویرایش کنید.

گفتم اینها تنها دو فایلی هستند که نیاز دارید. و این درست است. اما سایتی که ایجاد می کنید نسبتاً زشت خواهد بود. صفحه وب پیش‌فرض من از Bootstrap برای CSS استفاده می‌کند، اما شما احتمالاً می‌خواهید CSS خود را اضافه کنید تا ظاهر آن را تغییر دهید – به همراه، شاید، برخی جاوا اسکریپت و برخی از تصاویر. تمام فایل هایی که برای کارکرد سایت خود نیاز دارید باید به دایرکتوری /docs در مخزن شما اضافه شوند.

پس از رسیدن به این مرحله، می توانیم وب سایت شما را آزمایش کنیم. خوب، ابتدا باید Perlanet را نصب کنیم. دو راه برای انجام این کار وجود دارد. می توانید آن را از CPAN به همراه تمام وابستگی های (بسیار) آن – با استفاده از “cpan Perlanet” نصب کنید یا یک تصویر Docker وجود دارد که می توانید از آن استفاده کنید. در هر صورت، هنگامی که نرم افزار را نصب کردید، اجرای آن به سادگی اجرای “perlanet” است. این برای مدتی ادامه پیدا می‌کند و پس از اتمام، فایل‌های جدیدی به نام‌های “index.html” و “atom.xml” را در پوشه /docs پیدا خواهید کرد. روش مورد علاقه من برای آزمایش خروجی به صورت محلی استفاده از App::HTTPThis است. پس از نصب این برنامه، می‌توانید «http_this docs» را از دایرکتوری اصلی مخزن اجرا کنید و سپس به http://localhost:7007/index.html مراجعه کنید تا سایت تولید شده را ببینید (یا http://localhost:7007/atom xml. برای دیدن فید.

اکنون سیستمی برای ساختن سیاره جدید خود دارید. می‌توانید آن را روی سروری که به اینترنت متصل است اجرا کنید و یک cronjob برای بازسازی فایل هر چند ساعت یک بار راه‌اندازی کنید. و اینگونه بود که من تمام سیاره هایم را اداره می کردم. اما، اخیراً، به جای آن به اجرای آنها روی صفحات GitHub رفته ام. و این چیزی است که در ادامه به آن خواهیم پرداخت.

این دو بخش دارد. ما باید مخزن خود را طوری پیکربندی کنیم که یک سایت GitHub Pages مرتبط با آن باشد و همچنین باید GitHub Actions را برای بازسازی سایت هر چند ساعت یک بار پیکربندی کنیم. بیایید آن دو را به نوبه خود بگیریم.

روشن کردن صفحات GitHub به اندازه کافی ساده است. فقط کافی است به بخش “صفحات” در تنظیمات مخزن خود بروید. «GitHub Actions» را به عنوان منبع استقرار انتخاب کنید و کادر با علامت «اجرای HTTPS» را علامت بزنید. بعداً، می‌توانید به راه‌اندازی یک دامنه سفارشی برای سایت خود نگاه کنید، اما در حال حاضر، بیایید به URL پیش‌فرض که https://.github.io/ است، پایبند باشیم. هنوز چیزی ظاهر نمی‌شود، زیرا در مرحله بعد باید GitHub Actions را تنظیم کنیم.

راه اندازی یک گردش کار GitHub Action به سادگی اضافه کردن یک فایل YAML به فهرست /.github/workflows موجود در مخزن شما است. بدیهی است که ابتدا باید آن دایرکتوری را ایجاد کنید. در اینجا تعریف گردش کار برای Planet Perl آمده است (در فایلی به نام buildsite.yml است، اما این نام مهم نیست).

name: Generate web page

on:
  push:
    branches: '*'
  schedule:
    - cron: '37 */4 * * *'
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest
    container: davorg/perl-perlanet:latest

    steps:
    - name: Checkout
      uses: actions/checkout@v3

    - name: Create pages
      run: |
        mkdir -p docs
        perlanet > perlanet.log 2>&1
    - name: Commit new page
      if: github.repository == 'davorg/planetperl'
      run: |
        git config --global --add safe.directory /__w/planetperl/planetperl
        GIT_STATUS=$(git status --porcelain)
        echo $GIT_STATUS
        git config user.name github-actions[bot]
        git config user.email 41898282+github-actions[bot]@users.noreply.github.com
        git add docs/
        if ["$GIT_STATUS" != ""]; then git commit -m "Automated Web page generation"; fi
        if ["$GIT_STATUS" != ""]; then git push; fi
    - name: Archive perlanet logs
      uses: actions/upload-artifact@v3
      with:
        name: perlanet.log
        path: ./perlanet.log
        retention-days: 3

    - name: Update pages artifact
      uses: actions/upload-pages-artifact@v1
      with:
        path: docs/

  deploy:
    needs: build
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v2

بخش اول فایل رویدادهایی را تعریف می کند که این گردش کار را راه اندازی می کند. من سه محرک تعریف کرده ام:

1. فشار دادن یک تعهد. من می‌توانم در اینجا باهوش‌تر باشم و فقط زمانی کار کنم که فایل‌های خاصی تغییر کنند (مثلاً پیکربندی یا index.tt)
2. بر اساس یک برنامه مثال من در 37 دقیقه قبل از ساعت هر چهار ساعت اجرا می شود (بنابراین در 04:37، 08:37 و غیره)
3. به صورت دستی. راه‌انداز «workflow_dispatch» دکمه‌ای را به صفحه «اقدامات» مخزن در GitHub اضافه می‌کند که به شما این امکان را می‌دهد تا هر زمان که بخواهید گردش کار را به صورت دستی اجرا کنید.

به دنبال آن، مشاغلی را که باید اجرا شوند و مراحل تشکیل دهنده آن مشاغل را تعریف می کنیم. ما دو کار داریم – یکی که نسخه جدید سایت را می سازد و دیگری که آن سایت جدید را در صفحات گیت هاب مستقر می کند. به خاطر دارید که قبلاً ذکر کردم که یک کانتینر Perlanet در Docker Hub وجود دارد؟ خوب، خواهید دید که کار ساخت بر روی آن ظرف اجرا می شود. این به این دلیل است که کشیدن یک کانتینر از داکر هاب سریعتر از استفاده از یک ظرف استاندارد اوبونتو و نصب Perlanet است.

مراحل انجام این کارها باید کاملاً قابل توضیح باشد. اساسا، ما مخزن را بررسی می کنیم، “perlanet” را برای ساخت سایت اجرا می کنیم و سپس محتویات دایرکتوری /docs را در سرور GitHub Pages مستقر می کنیم.

هنگامی که این فایل را ایجاد کردید و آن را به مخزن خود اضافه کردید، جزئیات این گردش کار را در برگه “عملکردها” در مخزن خود خواهید دید. و هر زمان که تغییری را فشار دهید یا زمانی که اجرای برنامه‌ریزی شده انجام می‌شود (یا دکمه اجرای دستی را فشار می‌دهید)، گزارش‌هایی را برای اجرا مشاهده می‌کنید و (امیدواریم) وب‌سایت شما به‌روزرسانی می‌شود تا حاوی آخرین داده‌ها باشد.

من فکر می کنم شما می توانید یک سیاره جدید را در حدود نیم ساعت راه اندازی کنید. اوه، و اگر مخزن خود را با عنوان “perlanet” برچسب گذاری کنید، به طور خودکار به The Planetarium اضافه می شود.

پس برای چی منتظری؟ دوست دارید چه سیاره ای بسازید؟

پست ساخت سیارات با پرلانت و گیت هاب اولین بار در پرل هکس پدیدار شد.