diff --git a/docs/run_a_new_lister.rst b/docs/run_a_new_lister.rst new file mode 100644 --- /dev/null +++ b/docs/run_a_new_lister.rst @@ -0,0 +1,73 @@ + +:orphan: + +.. _run-lister-tutorial: + +Tutorial: run a lister within docker-dev in just a few steps +===================================================================== + +It is a good practice to run your new lister in docker-dev. This provides an almost +production-like environment. Testing the lister in docker dev prior to deployment +reduces the chances of encountering errors when turning it for production. +Here are the steps you need to follow to run a lister within your local environment. + + +1. You must edit the docker-compose override file (`docker-compose.override.yml`). + following the sample provided :: + + version: '2' + + services: + swh-lister: + volumes: + - "$SWH_ENVIRONMENT_HOME/swh-lister:/src/swh-lister" + + The file named `docker-compose.override.yml` will automatically be loaded by + `docker-compose`.Having an override makes it possible to run a docker container + with some swh packages installed from sources instead of using the latest + published packages from pypi. For more details, you may refer to README.md + present in `swh-docker-dev`. +2. Follow the instruction mentioned under heading **Preparation steps** and + **Configuration file sample** in README.md of swh-lister. +3. Make sure to run storage (5002) and scheduler (5008) services locally. + You may use the following command to run docker:: + + ~/swh-environment/swh-docker-dev$ docker-compose up -d + +4. Add the lister task-type in the scheduler. For example, if you want to + add pypi lister task-type :: + + ~/swh-environment$swh scheduler task-type add list-gnu-full \ + "swh.lister.gnu.tasks.GNUListerTask" "Full GNU lister" \ + --default-interval '1 day' --backoff-factor 1 + + You can check all the task-type by:: + + ~/swh-environment$swh scheduler task-type list + Known task types: + list-bitbucket-incremental: + Incrementally list BitBucket + list-cran: + Full CRAN Lister + list-debian-distribution: + List a Debian distribution + list-github-full: + Full update of GitHub repos list + list-github-incremental: + ... + + If your lister is creating new loading task not yet registered, you need + to register that task type as well. Like for GNU lister:: + + ~/swh-environment$swh scheduler task-type add load-gnu-full recurring \ + "GNU Loader" + +5. Run your lister with the help of scheduler cli. You need to add the task in + the scheduler using its cli. For example, you need to execute this command + to run gnu lister :: + + ~/swh-environment$swh scheduler --url http://localhost:5008/ task add \ + list-gnu-full --policy oneshot + +After the execution of lister is complete, you can see the loading task created. + ~/swh-environment/swh-lister$swh scheduler task list diff --git a/docs/tutorial.rst b/docs/tutorial.rst --- a/docs/tutorial.rst +++ b/docs/tutorial.rst @@ -56,18 +56,18 @@ 3. Populate a work queue for fetching and ingesting source repositories. Steps 1 and 3 are generic problems, so they can get generic solutions hidden -away in base code, most of which never needs to change. That leaves us to -implement step 2, which can be trivially done now for services with clean web +away in the base code, most of which never needs to change. That leaves us to +implement step 2, which can be trivially done now for services with a clean web APIs. -In the new code we've tried to hide away as much generic functionality as +In the new code, we've tried to hide away as much generic functionality as possible, turning it into set-and-forget plumbing between a few simple customized elements. Different hosting services might use different network protocols, rate-limit messages, or pagination schemes, but, as long as there is some way to get a list of the hosted repositories, we think that the new base code will make getting those repositories much easier. -First let me give you the 30,000 foot view… +First, let me give you the 30,000 foot view… The old GitHub-specific lister code looked like this (265 lines of Python): @@ -164,6 +164,16 @@ looks much simpler when we look at the actual implementations of the two new-style indexing listers we currently have… +When developing a new lister, it's important to test. For this, add the tests +(check `swh/lister/*/tests/`) and register the celery tasks in the main +conftest.py (`swh/lister/core/tests/conftest.py`). + +Another important step is to actually run it within the +docker-dev (:ref:`run-lister-tutorial`). + +After tests, it's suggested to run your new lister in docker-dev: +`How to run a lister `. + This is the entire source code for the BitBucket repository lister:: # Copyright (C) 2017 the Software Heritage developers