{"id":16547732,"url":"https://github.com/kachkaev/special-internet-archive","last_synced_at":"2025-08-10T16:06:55.242Z","repository":{"id":38127361,"uuid":"478326990","full_name":"kachkaev/special-internet-archive","owner":"kachkaev","description":"Tooling to archive web pages","archived":false,"fork":false,"pushed_at":"2025-06-15T13:10:05.000Z","size":3487,"stargazers_count":6,"open_issues_count":1,"forks_count":1,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-06-20T13:52:12.386Z","etag":null,"topics":["playwright","wayback-machine"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kachkaev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-04-05T22:59:04.000Z","updated_at":"2025-06-15T13:10:09.000Z","dependencies_parsed_at":"2023-02-12T19:01:21.418Z","dependency_job_id":"f68c08f0-e87b-45a1-9bd5-058621d08334","html_url":"https://github.com/kachkaev/special-internet-archive","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/kachkaev/special-internet-archive","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kachkaev%2Fspecial-internet-archive","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kachkaev%2Fspecial-internet-archive/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kachkaev%2Fspecial-internet-archive/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kachkaev%2Fspecial-internet-archive/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kachkaev","download_url":"https://codeload.github.com/kachkaev/special-internet-archive/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kachkaev%2Fspecial-internet-archive/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269747895,"owners_count":24469102,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-10T02:00:08.965Z","response_time":71,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["playwright","wayback-machine"],"created_at":"2024-10-11T19:22:54.600Z","updated_at":"2025-08-10T16:06:55.189Z","avatar_url":"https://github.com/kachkaev.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Special Internet Archive 📜 Спецархив\n\nThis project was created in response to a [“special military operation”](https://en.wikipedia.org/wiki/2022_Russian_invasion_of_Ukraine), which Russian army started against Ukraine in February 2022.\n“Special Internet Archive” aims to automate the preservation of related online content, thus providing future researchers with historic data to analyse.\n\nWars of the 20\u003csup\u003eth\u003c/sup\u003e century left physical artefacts like newspapers, letters, diaries and films.\nSome of these objects were studied only decades later and became crucial for shedding some light on the tragic past.\nWhen a war takes place in the digital-first era, people are surrounded by vast streams of online content, but they rarely think about how fragile this information is.\nA website is only available while a server is running and a social media post is ‘everywhere’ only until it is deleted by the author or a moderator.\nThus, if we don’t proactively preserve the present, future generations won’t be able to study the past.\n\nThis repository helps archive public web pages before they are removed or edited.\nIt contains software that produces structured archive collections and orchestrates snapshot capturing.\nThe shape of the harvested data is compatible with git repositories or cloud storages like S3.\nCode architecture supports various web page sources (websites) as well as multiple snapshot generators, both local and third-party.\n\nThe initial version of the tooling only works with public VK communities.\nIt relies on [web.archive.org](https://web.archive.org) as a third-party snapshot generator and supplements it with local [Playwright](https://playwright.dev) snapshots.\nAlthough local snapshots are less accessible, they may contain content that third-party tools are unable to collect.\n\n“Special Internet Archive” does not aim to “capture the whole internet”.\nHowever, those modest datasets it helps collect might useful for the researches of the future.\n\nBased on the initial scope of the project, the instructions below are in Russian.\nThe software is written in TypeScript and its output uses English.\nThis repository can be used globally to create structured archive collections with any web pages.\n\n👀 [English version via Google Translate](https://translate.google.com/translate?sl=ru\u0026tl=en\u0026u=https://github.com/kachkaev/special-internet-archive/blob/main/README.md)\n\n## Об архиве\n\n### Основные принципы\n\nАрхив содержит _снимки_ (📸) и _аннотации_ (🏷) для публично доступных веб-страниц (🌐 адресов в интернете).\n\n```txt\n🌐 адрес 1            🌐 адрес 2          🌐 адрес 3      ...       🌐 адрес N\n📸 📸 📸 📸            📸 📸                                         📸 📸 📸 📸 📸 📸\n🏷                                        🏷                        🏷\n```\n\n📸 **Снимок веб-страницы** — это копия того, что выдавал сервер в конкретный момент времени.\nКаждому адресу веб-страницы может соответствовать несколько снимков.\nОни отличаются как временем, так и способом получения.\nСнимки бывают локальными (созданные волонтёром у себя на компьютере) и сторонними (созданные внешними сервисами).\n\nЛокальные снимки более гибкие и содержательные, потому что мы сами управляем инструментами для их создания.\nСторонние снимки содержат меньше информации, но считаются более надёжными.\nЧисто в теории локальные снимки могут быть подделкой, поэтому использование сторонних сервисов — это что-то вроде получения нотариально заверенных копий веб-страниц.\nДаже если весь наш архив с локальными снимками уничтожить, сторонние снимки всё равно имеют шанс дожить до потомков.\n\n🏷 **Аннотация веб-страницы** — это дополнительные данные, которые были добавлены человеком или программой в процессе архивации.\nЧастный случай аннотации — метки (теги).\nАннотации помогают собирать, структурировать и анализировать архивные данные, при этом хранятся отдельно от снимков веб-страниц.\n\n### Структура архива\n\nСодержимое архива разделено на коллекции.\nКаждая коллекция архива фокусируется на чём-то одном: например, _сообществах ВК в Энской области_.\nРазделение архива на коллекции упрощает параллельный сбор данных, а также их хранение и анализ.\n\n```txt\n🌐 🌐 🌐 🌐            🌐 🌐 🌐 🌐 🌐         🌐 🌐 🌐                   🌐 🌐 🌐\n🗃 коллекция 1        🗃 коллекция 2        🗃 коллекция 3    ...     🗃 коллекция N\n↕                     ↕                     ↕                        ↕\n👤                    👤👤👤                 👤                        👤👤\n```\n\nКоллекция архива — это обычная папка с файлами.\nМы не используем базы данных или закрытые форматы файлов, чтобы минимизировать зависимость архива от технологий для обработки данных.\nКлючевые форматы файлов в коллекции — [JSON](https://ru.wikipedia.org/wiki/JSON) и [ZIP](https://ru.wikipedia.org/wiki/ZIP).\n\nДля обмена собранными данными мы используем [гит](https://ru.wikipedia.org/wiki/Git) (систему контроля версий).\nЭто упрощает совместную работу над коллекциями архива и помогает делать резервные копии данных в процессе их сбора.\nСистема контроля версий не является обязательным компонентом для исследователей архива.\n\nКод в этом репозитории не является частью архива.\nСобранные данные не теряют ценность в случае утери или поломки скриптов.\n\n### Структура коллекции архива\n\n🗃 папка с коллекцией архива  \n🌐 папка с архивом одной веб-страницы (адреса в интернете)  \n📸 папка cо снимками одной веб-страницы  \n📂 любая другая папка\n\n📜 файл с первичными данными (включен в коллекцию)  \n⏳ временный файл (не включен в коллекцию)  \n🛠 технический файл (включен в коллекцию, но не имеет исторической ценности)\n\nВсе файлы и папки опциональные: они создаются в процессе запуска скриптов.\nЕсли вы что-то пока не видите в своей коллекции, ничего страшного.\n\n```txt\n🗃 [collection-dir-path]/\n\n  📂 snapshot-queues/\n\n    ⏳ some-third-party-generator.json\n    ⏳ some-local-generator.json\n    ⏳ some-other-third-party-generator.json\n\n\n  📂 web-pages/\n\n    📂 some/\n\n      📂 path/\n\n        📂 to/\n\n          🌐 some-web-page/\n          🌐 some-other-web-page/\n\n\n    📂 some-other-path/\n\n      🌐 another-web-page/\n      🌐 different-web-page/\n\n\n  🛠 .gitattributes\n  🛠 .gitignore\n  🛠 .prettierrc\n  🛠 README.md\n  ⏳ url-inbox.txt\n```\n\nПапка `📂 web-pages` содержит данные по веб-страницам коллекции.\nСтруктура этой папки определяется форматом интернет-адресов.\nНапример, `https://vk.com/wall-54321_111` соответствует папке `🌐 web-pages/vk/posts/-54321/111`.\n\nПапка `📂 snapshot-queues` используется при [создании снимков](#создание-снимков).\nФайл `⏳ url-inbox.txt` нужен [для регистрации веб-страниц](#регистрация-веб-страниц).\n\nПапка каждой веб-страницы имеет такую структуру:\n\n```txt\n🌐 some/path/to/some-web-page/\n\n  📸 snapshots/\n\n    📜 2022-03-10-011223z-some-local-generator.zip\n    ⏳ 2022-03-10-011223z-some-local-generator.zip.summary.json\n\n    ⏳ 2022-04-05-124312z-some-third-party-generator.zip\n    ⏳ 2022-04-05-124312z-some-third-party-generator.zip.summary.json\n\n    ⏳ 2022-04-27-071231z-some-other-third-party-generator.zip\n    ⏳ 2022-04-27-071231z-some-other-third-party-generator.zip.summary.json\n\n    📜 2022-05-02-182048z-some-local-generator.zip\n    ⏳ 2022-05-02-182048z-some-local-generator.zip.summary.json\n\n    ⏳ 2022-05-02-182440z-some-third-party-generator.zip\n    ⏳ 2022-05-02-182440z-some-third-party-generator.zip.summary.json\n\n\n  ⏳ snapshot-summary-combination.json\n  📜 web-page.json\n```\n\nВ файле `📜 web-page.json` хранится адрес веб-страницы, списки известных снимков (📸) и аннотация (🏷).\nЭто единственный обязательный файл в папке.\n\nПапка `📸 snapshots` предназначена для снимков веб-страницы.\nЛокальные снимки содержат первичные данные и поэтому становятся частью коллекции (📜).\nВнешние снимки — это временные файлы (⏳), так как их можно скачать заново.\n\n\u003c!-- ↑ Возможно, это допущение будет пересмотрено. --\u003e\n\nРядом со снимком веб-страницы находится сводка по этому снимку: `⏳ *.summary.json`.\nСводки [извлекаются из снимков скриптами](#извлечение-сводок-из-снимков) и содержат структурированные копии веб-страниц (например, список постов в ленте сообщества).\nФайлы сводок считаются временными, потому что в них есть только данные из снимков, то есть их можно пересоздать.\nФайл `⏳ snapshot-summary-combination.json` тоже генерируется локально и содержит комбинацию сводок (например, объединённый список постов за всё время архивации сообщества).\n\nВременны́е координаты в названиях файлов (`2022-04-05-124312z`) и внутри файлов (`\"2022-04-05T12:43:12Z\"`) используют часовой пояс [UTC](https://ru.wikipedia.org/wiki/%D0%92%D1%81%D0%B5%D0%BC%D0%B8%D1%80%D0%BD%D0%BE%D0%B5_%D0%BA%D0%BE%D0%BE%D1%80%D0%B4%D0%B8%D0%BD%D0%B8%D1%80%D0%BE%D0%B2%D0%B0%D0%BD%D0%BD%D0%BE%D0%B5_%D0%B2%D1%80%D0%B5%D0%BC%D1%8F) (MSK-03).\n[Согласно ISO 8601](\u003chttps://en.wikipedia.org/wiki/ISO_8601#Coordinated_Universal_Time_(UTC)\u003e), UTC обозначается литерой `Z` _(“Zulu time”)_.\nМы не убираем этот символ, чтобы не создавать путаницы с местным временем или временем по Москве.\n\n---\n\nРазбивка папки `📂 web-pages` на подпапки помогает упорядочить коллекцию, но не несёт в себе дополнительной информации.\nЛюбая подпапка с файлом `📜 web-page.json` считается папкой веб-страницы (🌐).\nВложенных папок веб-страниц быть не должно:\n\n```txt\n🌐 some/path/to/some-web-page/\n  📜 web-page.json\n\n\n❌ some/path/to/some-web-page/some/subfolder/\n  ❌ web-page.json\n```\n\n## Инструкции\n\nЧтобы собрать коллекцию архива, вам понадобятся:\n\n- базовое понимание [командной строки](https://ru.wikipedia.org/wiki/Интерфейс_командной_строки) (терминала),\n- небольшой опыт работы с [гитом](https://ru.wikipedia.org/wiki/Git) (системой контроля версий),\n- поверхностное знакомство с форматом [JSON](https://ru.wikipedia.org/wiki/JSON).\n\nВ качестве текстового редактора рекомендуется [VSCode](https://code.visualstudio.com) с расширениями\n[DotENV](https://marketplace.visualstudio.com/items?itemName=mikestead.dotenv),\n[Git Graph](https://marketplace.visualstudio.com/items?itemName=mhutchie.git-graph),\n[Git Lens](https://marketplace.visualstudio.com/items?itemName=eamodio.gitlens) и\n[Yaml](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml).\n\nВ упоминаемых папках и файлах `[project-dir-path]` условно обозначает локальную папку, которую вы выделили под проект.\nНапример, если на вашем компьютере это `/Users/me/projects/special-internet-archive`, то `[project-dir-path]/some-folder` в инструкциях означает `/Users/me/projects/special-internet-archive/some-folder`.\n\n### Требования к системе\n\nДля запуска скриптов подойдёт любой относительно современный компьютер с любой операционной системой (Linux, macOS, Windows).\nХватит 4-8 ГБ оперативной памяти и порядка 2-5 ГБ свободного места на диске.\n\n### Подготовка к работе\n\nЭти шаги достаточно выполнить один раз, даже если вы планируете сбор нескольких коллекций архива.\n\n1.  Убедитесь, что на машине установлены [гит](https://git-scm.com) (система контроля версий), [гит-лфс](https://git-lfs.github.com) (плагин для работы с большими файлами) и [нода](https://nodejs.org/ru) (среда запуска скриптов).\n    При установке ноды рекомендуется выбрать версию LTS.\n\n    Команды для проверки установки:\n\n    ```sh\n    git --version\n    ## покажет ≥ 2.30\n    \n    git-lfs --version\n    ## покажет ≥ 3.0\n    \n    node --version\n    ## покажет ≥ 16.14, \u003c 17 или ≥ 18.0, \u003c 19\n    ```\n\n1.  Установите последнюю версию [ярна](https://yarnpkg.com) (менеджера зависимостей):\n\n    ```sh\n    npm install --global yarn\n    ```\n\n    Команда для проверки установки:\n\n    ```sh\n    yarn --version\n    ## покажет ≥ 1.22\n    ```\n\n1.  [Клонируйте](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository) этот репозиторий в папку `[project-dir-path]/tooling`.\n\n    Перейдите в консоли в заранее созданную папку `[project-dir-path]`:\n\n    ```sh\n    cd \"[project-dir-path]\"\n    \n    ## пример:\n    ## cd \"/Users/bob/projects/special-internet-archive\"\n    ```\n\n    Название этой папки должно появиться слева от места ввода команды.\n\n    Запустите клонирование:\n\n    ```sh\n    git clone https://github.com/kachkaev/special-internet-archive.git tooling\n    ```\n\n    В качестве самопроверки убедитесь, что на вашем компьютере появился файл `[project-dir-path]/tooling/README.md`.\n\n    Если результат клонирования репозитория оказался в другой папке, например, `[project-dir-path]/special-archive-tooling` или `[project-dir-path]/archive/tooling`, то папку желательно перенести.\n    Связь с гитхабом при этом не потеряется.\n\n1.  Откройте терминал, перейдите в папку `[project-dir-path]/tooling`:\n\n    ```sh\n    cd \"[project-dir-path]/tooling\"\n    \n    ## пример:\n    ## cd \"/Users/bob/projects/special-internet-archive/tooling\"\n    ```\n\n1.  Будучи в папке `[project-dir-path]/tooling`, установите зависимые библиотеки:\n\n    ```sh\n    yarn install\n    ```\n\n    Это займёт пару минут.\n\n1.  Будучи в папке `[project-dir-path]/tooling`, создайте пустой файл `.env.local`:\n\n    ```sh\n    yarn exe scripts/1-chores/ensure-dot-env-local.script.ts\n    ```\n\n    Запуск этой консольной команды помогает проверить общую работоспособность скриптов.\n    Если возникла ошибка, следует заново пройтись по инструкции (видимо, что-то пропустили).\n\n### Настройка коллекции архива\n\nПеред выполнением шагов в этом разделе вам надо получить доступ к непубличному репозиторию с данными.\nДля этого свяжитесь с автором скриптов или кем-то из телеграм-чата [@ruarxivechat](https://t.me/ruarxivechat).\nВы должны быть зарегистрированным пользователем на гитхабе и сообщить свой ник.\n\nПосле получения доступа:\n\n1.  Создайте локальную папку `[project-dir-path]/data/collections`.\n\n1.  Клонируйте созданную для вас ветку в папку `🗃 [project-dir-path]/data/collections/[collection-id]`.\n\n    Чтобы клонировать, в консоли введите команду из папки `[project-dir-path]/data`:\n\n    ```sh\n    git clone https://[github-username]:[personal-access-token]@github.com/[repository].git --branch=collections/[collection-id] --single-branch collections/[collection-id]\n    \n    ## пример:\n    ## git clone https://bob:ghp_llNyHjFzdKimHctg0JDPOGLsPgIvmTPevAKs@github.com/example/repo.git --branch=collections/my-collection --single-branch collections/my-collection\n    ```\n\n    - `[github-username]` — это ваш ник на гитхабе.\n    - `[personal-access-token]` — это ваш персональный токен аутентификации для доступа к приватному репозиторию ([инструкция](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)).\n    - `[repository]` - это названия репозитория, где будет храниться ваша коллекция архива.\n    - `[collection-id]` — это название коллекции (например, `region-ru-pnz` или `topic-xyz`).\n      Название папки соответствует названию ветки репозитория с данными (`collections/[collection-id]`).\n\n1.  Откройте файл `[project-dir-path]/tooling/.env.local` как текстовый и укажите путь к коллекции архива.\n    Это делается добавлением такой строчки:\n\n    ```ini\n    COLLECTION_DIR_PATH=[project-dir-path]/data/collections/[collection-id]\n\n    ## пример:\n    ## COLLECTION_DIR_PATH=/Users/bob/projects/special-internet-archive/data/collections/my-collection\n    ```\n\n### Регистрация веб-страниц\n\nЧтобы начать архивировать веб-страницы, необходимо добавить в коллекцию архива первые несколько ссылок.\nПока что это могут быть только сообщества ВК (`https://vk.com/typical_ensk`).\nили прямые ссылки на посты (`https://vk.com/wall-123-456`).\nСсылки на посты регистрировать не обязательно, так как они автоматически извлекаются из зарегистрированных сообществ.\n\nРегистрировать новые ссылки в коллекцию архива можно в любой момент.\nЖелательно держать коллекцию сфокусированной на чём-то одном, то есть не сваливать все ссылки в кучу.\nЭто упростит координацию сбора данных и их анализ.\n\n1.  Создайте файл `⏳ [collection-dir-path]/url-inbox.txt`.\n    Это можно сделать вручную или скриптом:\n\n    ```sh\n    yarn exe scripts/2-registration/1-ensure-url-inbox-exists.script.ts\n    ```\n\n1.  Накидайте в файл `⏳ [collection-dir-path]/url-inbox.txt` ссылки, которые хотите зарегистрировать.\n    Каждая строчка в файле должна содержать только одну ссылку.\n    Пустые строчки или строчки без ссылок проигнорируются.\n    Если вы копируете ссылки из таблицы, вам не придётся ничего менять.\n\n    Пример:\n\n    ```txt\n    https://vk.com/id123\n\n    https://vk.com/group123\n    https://vk.com/public123\n    https://vk.com/something\n    какой-то текст между ссылками\n    https://vk.com/wall-123-456\n    ```\n\n1.  Запустите скрипт для регистрации всех ссылок из файла `⏳ [collection-dir-path]/url-inbox.txt`:\n\n    ```sh\n    yarn exe scripts/2-registration/2-register-from-url-inbox.script.ts\n    ```\n\n    Это создаст файлы `📜 [collection-dir-path]/web-pages/**/web-page.json`.\n\n    Повторные попытки зарегистрировать одну и ту же ссылку будут проигнорированы.\n    Уже собранные данные при этом не потеряются.\n\n1.  ![][опционально]  \n    Запустите скрипт, который удалит все зарегистрированные ссылки из файла `⏳ [collection-dir-path]/url-inbox.txt`.\n    Это поможет разглядеть ссылки, которые не получилось добавить.\n\n    ```sh\n    yarn exe scripts/2-registration/3-clean-up-url-inbox.script.ts\n    ```\n\n    Пример:\n\n    ```txt\n    https://vk.com/public123\n    https://vk.com/unsupported/url\n    какой-то текст между ссылками\n    https://vk.com/group123\n\n    https://vk.com/wall-123-456\n    ещё текст\n    https://unsupported.example.com\n    ```\n\n    ↓\n\n    ```txt\n    https://vk.com/unsupported/url\n    какой-то текст между ссылками\n\n    ещё текст\n    https://unsupported.example.com\n    ```\n\n### Создание снимков\n\nПроцесс создания новых снимков состоит из трёх действий: инвентаризации существующих снимков, составления очереди заявок на новые снимки и исполнения очереди.\nЭти действия выполняются независимо для каждого генератора снимков.\n\n#### Сторонние снимки: Wayback Machine\n\n[Wayback Machine](https://ru.wikipedia.org/wiki/Wayback_Machine) — это некоммерческий онлайн-архив интернета.\nОн [заблокирован в России](https://ru.wikipedia.org/wiki/Wayback_Machine#%D0%91%D0%BB%D0%BE%D0%BA%D0%B8%D1%80%D0%BE%D0%B2%D0%BA%D0%B8), поэтому для работы со снимками в этом хранилище [вам понадобится VPN](https://roskomsvoboda.org/cards/card/whydoyouneedVPN/).\n\n[web.archive.org](https://web.archive.org) пока что выступает в роли единственного стороннего хранилища.\nВозможно, в будущем мы подключим и другой онлайн-архив: [archive.ph](https://archive.ph).\nКомбинирование хранилищ повышает надёжность и полноту архива.\n\n1.  Проведите инвентаризацию существующих снимков Wayback Machine:\n\n    ```sh\n    ## 🌍 если вы в России, включите VPN\n    yarn exe scripts/3-snapshots/wayback-machine/1-update-inventory.script.ts\n    ```\n\n    Этот скрипт скачает список уже существующих снимков для веб-страниц из нашей коллекции.\n    Среди них могут быть как снимки, которые мы запрашивали ранее, так и снимки, которые делал кто-то другой.\n\n    Результат будет сохранён в разделе `snapshotInventoryLookup` файлов `📜 web-page.json`.\n\n    При повторном запуске скрипт пропустит веб-страницы, которые проверяли до 60 минут назад.\n    Этот интервал контролируется переменной окружения `INVENTORY_DURABILITY_IN_MINUTES`.\n\n    Если у веб-страницы есть недавно созданный снимок, скрипт её тоже пропустит.\n    Такой режим работы ускоряет повторную инвентаризацию крупных коллекций архива.\n    Чтобы провести инвентаризацию и для страниц с недавними снимками, задайте переменную окружения `EAGER=true`.\n\n1.  Составьте очередь заявок на новые снимки:\n\n    ```sh\n    yarn exe scripts/3-snapshots/wayback-machine/2-compose-queue.script.ts\n    ```\n\n    Этот скрипт пройдётся по коллекции веб-страниц и посмотрит на время последних известных нам снимков в Wayback Machine.\n    Веб-страницы, которые давно не загружались, будут добавлены в очередь.\n    Интервал между запрашиваемыми снимками зависит от типа и возраста конкретной веб-страницы.\n    Настроить его пока что нельзя.\n\n1.  Обработайте очередь заявок на новые снимки:\n\n    ```sh\n    ## 🌍 если вы в России, включите VPN\n    yarn exe scripts/3-snapshots/wayback-machine/3-process-queue.script.ts\n    ```\n\n    Скрипт посмотрит на адреса веб-страниц в очереди и отправит каждую из них через форму https://web.archive.org/save.\n    Обработку очереди можно прерывать и перезапускать.\n    Успешные заявки обрабатываться по второму разу не будут.\n\n    \u003e 🟡 **Wayback Machine принимает до 500 запросов на снимки в день**  \n    \u003e Если вы превысите этот лимит, скрипт выдаст ошибку и завершится:\n    \u003e\n    \u003e ```txt\n    \u003e API limits reached. Try using another internet connection or continue tomorrow\n    \u003e ```\n    \u003e\n    \u003e Запустите скрипт через день, либо подключитесь к интернету как-то по-другому (поменяйте свой IP-адрес).\n\n#### Локальные снимки: Playwright\n\n[Playwright](https://playwright.dev) — инструмент для тестирования веб-приложений.\nПо сути это обёртка вокруг веб-браузера, которая позволяет автоматизировать взаимодействие с сайтами.\nПрограмма может открывать веб-страницы, нажимать на ссылки и кнопки, проматывать содержимое, вводить текст и так далее.\nPlaywright умеет сохранять такие автоматизированные сессии в виде очень детализированных отпечатков ([traces](https://playwright.dev/docs/trace-viewer)).\nОтпечаток Playwright — это что-то вроде слайдов в презентации, только в формате `zip`.\nВнутри архива находятся все необходимые ресурсы для отображения «слайдов»: разметка, стили и картинки.\nКаждый «слайд» соответствует одному действию (например, прокрутка веб-страницы вниз).\n\nПрограмма Playwright имеет открытый исходный код и свободную лицензию.\nФормат отпечатков тоже открыт и поэтому должен прочитаться даже в далёком будущем.\nПример отпечатка веб-страницы в Playwright [доступен на сайте проекта](https://trace.playwright.dev/?trace=https://demo.playwright.dev/reports/todomvc/data/cb0fa77ebd9487a5c899f3ae65a7ffdbac681182.zip).\n\nДля тестировщиков веб-приложений отпечатки Playwright — это средство отладки кода.\nДля нас отпечатки Playwright — это возможность создать компактные, но содержательные локальные снимки веб-страниц.\n\n1.  Проведите инвентаризацию существующих снимков Playwright:\n\n    ```sh\n    yarn exe scripts/3-snapshots/playwright/1-update-inventory.script.ts\n    ```\n\n    Результат будет сохранён в разделе `snapshotInventoryLookup` файлов `📜 web-page.json`.\n\n1.  Составьте очередь заявок на новые снимки:\n\n    ```sh\n    yarn exe scripts/3-snapshots/playwright/2-compose-queue.script.ts\n    ```\n\n    Этот скрипт пройдётся по коллекции веб-страниц и посмотрит на время последних известных нам снимков в Playwright.\n    Веб-страницы, которые давно не загружались, будут добавлены в очередь.\n    Интервал между запрашиваемыми снимками зависит от типа и возраста конкретной веб-страницы.\n    Настроить его пока что нельзя.\n\n    В очередь пока что добавляются только страницы сообществ, потому что ценность локальных снимков постов такая же, как у Wayback Machine.\n\n1.  Обработайте очередь заявок на новые снимки:\n\n    ```sh\n    yarn exe scripts/3-snapshots/playwright/3-process-queue.script.ts\n    ```\n\n    Обработку очереди можно прерывать и перезапускать.\n    Успешные заявки обрабатываться по второму разу не будут.\n\n### Извлечение сводок из снимков\n\nСнимки веб-страниц содержат «сырые» данные: разметку, стили и картинки.\nМы заранее не знаем, что из этого ценно, поэтому разделяем сбор «сырых» данных и их обработку.\n\nЧтобы автоматизировать архивацию постов ВК, нам нужно «прочитать» ленты сообществ и найти в них ссылки типа `https://vk.com/wall-123-456`.\nСначала мы разбираем известные нам снимки и извлекаем сводку по каждому из них.\nТак как у каждой веб-страницы может быть по несколько снимков, мы комбинируем полученные сводки отдельным скриптом.\n\n#### Сторонние снимки: Wayback Machine\n\n\u003e 🚧 эта секция — задел на будущее; её можно пропустить\n\n1.  Проведите повторную инвентаризацию существующих снимков.\n    Сервису [web.archive.org](https://web.archive.org) нужно время для создания новых снимков, поэтому желательно подождать минут 10-30 с момента отправки заявок.\n\n    ```sh\n    ## 🌍 если вы в России, включите VPN\n    yarn exe scripts/4-snapshot-summaries/wayback-machine/1-update-inventory.script.ts\n    ```\n\n    Результат будет сохранён в разделе `snapshotInventoryLookup` файлов `📜 web-page.json`.\n\n1.  Извлеките сводки из снимков:\n\n    ```sh\n    ## 🚧 скрипт пока ничего не делает, но это не препятствует сбору данных\n    yarn exe scripts/4-snapshot-summaries/wayback-machine/2-extract-summaries.script.ts\n    ```\n\n    Этот скрипт скачает известные нам снимки из [web.archive.org](https://web.archive.org) в `⏳ [web-page-dir-path]/snapshots/*-wayback-machine.zip` и создаст файл `⏳ [web-page-dir-path]/snapshots/*-wayback-machine.zip.summary.json` для каждого снимка.\n\n#### Локальные снимки: Playwright\n\n1.  Проведите инвентаризацию существующих снимков:\n\n    ```sh\n    yarn exe scripts/4-snapshot-summaries/playwright/1-update-inventory.script.ts\n    ```\n\n    Результат будет сохранён в разделе `snapshotInventoryLookup` файлов `📜 web-page.json`.\n\n1.  Извлеките сводки из снимков:\n\n    ```sh\n    yarn exe scripts/4-snapshot-summaries/playwright/2-extract-summaries.script.ts\n    ```\n\n    Этот скрипт создаст файл `⏳ [web-page-dir-path]/snapshots/*-playwright.zip.summary.json` для каждого файла `📜 [web-page-dir-path]/snapshots/*-playwright.zip`.\n\n    Пока что извлекается только список постов в лентах сообществ.\n\n#### Комбинация сводок\n\nПосле запуска предыдущих скриптов у нас есть сводки по каждому снимку: `⏳ [web-page-dir-path]/snapshots/*.summary.json`.\nИнформация в этих файлах частично повторяется, поэтому мы комбинируем сводки в файлы `⏳ [web-page-dir-path]/snapshot-summary-combination.json`:\n\n```sh\nyarn exe scripts/4-snapshot-summaries/extract-summary-combinations.script.ts\n```\n\n### Аннотация веб-страниц\n\n\u003e 🚧 эта секция — задел на будущее; её можно пропустить\n\nИмея комбинацию сводок, мы можем аннотировать веб-страницу: добавить метки, указать релевантные ссылки и так далее.\nПо задумке эта задача будет выполняться через веб-интерфейс методом _визуальной аналитики_ ([visual analytics](https://en.wikipedia.org/wiki/Visual_analytics)).\nКоординатор архива откроет веб-интерфейс командой `yarn dev`, увидит содержимое коллекции архива и сможет редактировать аннотацию каждой веб-страницы.\n\nПока веб-интерфейса нет, воспользуйтесь авто-аннотацией:\n\n```sh\n## 🚧 скрипт пока ничего не делает, но это не препятствует сбору данных\nyarn exe scripts/5-annotations/extract-from-snapshot-summary-combinations.script.ts\n```\n\nРезультат работы скрипта будет сохранён в разделе `annotation` файлов `📜 web-page.json`.\n\n### Работа с результатом\n\n#### Резервная копия данных\n\nЗапуск скриптов меняет содержимое папки `🗃 [project-dir-path]/data/collections/[collection-id]`.\nЧтобы не потерять ценные исторические данные, важно периодически синхронизировать коллекцию архива с гитхабом.\n\nСкрипты запускают синхронизацию автоматически.\nЧтобы это отключить, установите переменную окружения `AUTO_SYNC_COLLECTION=false`.\nДля синхронизации коллекции архива вручную есть скрипт:\n\n```sh\nyarn exe scripts/6-results/sync-collection.script.ts\n```\n\nОни равносилен выполнению таких команд:\n\n```sh\ncd \"[project-dir-path]/data/collections/[collection-id]\"\ngit add --all\ngit commit --message \"Update collection\"\ngit push\n```\n\n### Развитие коллекции\n\n#### Расширение перечня веб-страниц\n\nНакопленные снимки и аннотации — это потенциальный источник новых веб-страниц в коллекции.\nНапример, лента сообщества ВК содержит ссылки на отдельные посты, а эти веб-страницы считаются релевантными.\nПользуясь уже собранными данными, мы можем расширять коллекцию архива без ручного сбора ссылок.\n\n1.  Запустите скрипт, который найдёт релевантные ссылки в собранных данных и добавит их в файл `⏳ [collection-dir-path]/url-inbox.txt`.\n    Например, релевантными станут ссылки на общественно значимые посты в ленте сообществ.\n    Релевантность определяются по заранее заданным ключевым словам, в будущем это будет настраиваться.\n\n    ```sh\n    yarn exe scripts/2-registration/1-auto-populate-url-inbox-with-relevant-urls.script.ts\n    ```\n\n1.  ![][опционально]  \n    Откройте файл `⏳ [collection-dir-path]/url-inbox.txt` для проверки или ручного редактирования.\n\n1.  Вернитесь в раздел [Регистрация веб-страниц](#регистрация-веб-страниц) и продолжите с третьего пункта.\n\n    Чтобы держать коллекцию в обновлённом состоянии, весь процесс сбора данных рекомендуется повторять раз в несколько дней.\n    Самый лёгкий способ развивать коллекцию архива описан ниже.\n\n#### Комбинированный запуск скриптов\n\nЗапуск скриптов по одному помогает архиваторам разобраться в процессе сбора данных, а разработчикам — улучшать код.\nЧтобы держать архив в актуальном состоянии, нам надо перезапускать скрипты раз в несколько дней для каждой коллекции.\nЭто может быть утомительным.\n\nДля запуска всего процесса сбора и обработки данных существует комбинированный скрипт:\n\n```sh\n## 🌍 если вы в России, включите VPN\nyarn exe scripts/1-chores/evolve-collection.script.ts\n```\n\nСмысл комбинированного скрипта — запустить все необходимые команды в нужном порядке.\n\n\u003c!--\nЕсли на последнем шаге в файле `⏳ [collection-dir-path]/url-inbox.txt` появляются новые ссылки, процесса сбора и обработки данных повторяется.\nАвтоповтор можно отключить переменной окружения `COLLECTION_EVOLVEMENT_MODE=once`.\n--\u003e\n\nКомбинированный скрипт подойдет как для обновления, так и для первичного наполнения коллекций архива.\nЕсли коллекция новая, киньте несколько ссылок в файл `⏳ [collection-dir-path]/url-inbox.txt` перед тем, как запускать скрипт.\nСсылки можно докидывать в любой момент — это расширит коллекцию.\n\n### Работа с несколькими коллекциями\n\nАрхитектура проекта позволяет управлять несколькими коллекциями архива с одного компьютера.\nСтруктура папок в этом случае выглядит так:\n\n```txt\n📁 [project-dir-path]/\n\n  📁 tooling/\n\n  📁 data/\n\n    📁 collections/\n\n      🗃 [collection-id-1]/\n\n      🗃 [collection-id-2]/\n\n         ...\n\n      🗃 [collection-id-n]/\n```\n\nЕсли вы работайте с несколькими коллекциями, меняйте переменную `COLLECTION_DIR_PATH` между запусками скриптов.\nЭто делается в файле `[project-dir-path]/tooling/.env.local`.\n\n[опционально]: https://img.shields.io/badge/-опционально-white.svg\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkachkaev%2Fspecial-internet-archive","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkachkaev%2Fspecial-internet-archive","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkachkaev%2Fspecial-internet-archive/lists"}