getting_started: install swh packages in a virtualenv

Reviewers: zack

Subscribers: zack

Differential Revision: https://forge.softwareheritage.org/D430

docs/getting-started.rst

@@ -27,7 +27,7 @@ need the `mr <http://myrepos.branchable.com/>`_ tool. Once you have installed
 
   cd swh-environment
   bin/update
-  
+
 .. IMPORTANT::
 
    From now on this tutorial will assume that you **run commands listed below
@@ -35,57 +35,32 @@ need the `mr <http://myrepos.branchable.com/>`_ tool. Once you have installed
 
 For periodic repository updates just re-run ``bin/update``.
 
-From now on you will need to have a ``PYTHONPATH`` environment variable that
-allows to find Python modules in the ``swh`` namespace. To that end you can
-source the ``pythonpath.sh`` snippet from swh-environment::
-
-  source pythonpath.sh
-
-To make setting ``PYTHONPATH`` easier in the future, you might want to define a
-shell alias, e.g.::
-
-  alias swh-pythonpath='cd /path/to/swh-environment/ ; source pythonpath.sh ; cd - > /dev/null'
 
+Step 1 --- install base dependencies
+------------------------------------
 
-Step 1 --- install dependencies
--------------------------------
-
-You need to install three types of dependencies: Python modules, Node.js
+You need to install three types of dependencies: some base packages, Node.js
 modules (for the web app), and Postgres (as storage backend).
 
+Package dependencies
+~~~~~~~~~~~~~~~~~~~~
 
-Python modules
-~~~~~~~~~~~~~~
-
-You can install Python modules using ``pip3`` via the following helper::
-
-  sudo bin/pip-install-deps
-
-``pip-install-deps`` accepts additional ``pip3 install`` options so, e.g., if
-you want to install Python modules as a user rather than system wide you can do
-something like this instead::
-
-  bin/pip-install-deps --user
-
-If you want to see the list of Python dependencies, e.g., to install them by
-hand or via your package manager, you can use a related helpe::
-
-  bin/pip-ls-deps
+Software Heritage requires some dependencies that are usually packaged by your
+package manager. On Debian/Ubuntu-based distributions::
 
+  sudo apt install python3 libsvn-dev postgresql nodejs npm
 
 Postgres
 ~~~~~~~~
 
 You need a running Postgres instance with administrator access (e.g., to create
-databases). On Debian/Ubuntu based distributions it should be as easy as::
-
-  sudo apt install postgresql
+databases). On Debian/Ubuntu based distributions, the previous step
+(installation) should be enough.
 
 For other platforms and more details refer to the `PostgreSQL installation
-documnetation
+documentation
 <https://www.postgresql.org/docs/current/static/tutorial-install.html>`_.
 
-
 Node.js modules
 ~~~~~~~~~~~~~~~
 
@@ -93,7 +68,6 @@ If you want to run the web app to browser your local archive you will need some
 Node.js modules, in particular to pack web resources into a single compact
 file. To that end the following should suffice::
 
-  sudo apt install nodejs npm
   cd swh-web
   npm install
   cd -
@@ -102,7 +76,30 @@ You are now good to go with all needed dependencies on your development
 machine!
 
 
-Step 2 --- set up storage
+Step 2 --- install SWH in a virtualenv
+--------------------------------------
+
+From now on you will need to work in a `virtualenv
+<https://docs.python.org/3/library/venv.html>`_ containing the Python
+environment with all the Software Heritage modules and dependencies. To that
+end you can do (once)::
+
+  python3 -m venv .venv
+
+Then, activate the virtualenv (do this every time you start working on Software
+Heritage)::
+
+  source .venv/bin/activate
+
+Python modules
+~~~~~~~~~~~~~~
+
+You can install the SWH Python modules and their dependencies using::
+
+  pip install $( bin/pip-swh-packages )
+
+
+Step 3 --- set up storage
 -------------------------
 
 Then you will need a local storage service that will archive and serve source
@@ -165,7 +162,7 @@ You can now run the storage server like this::
   python3 -m swh.storage.api.server --host localhost --port 5002 ~/.config/swh/storage/storage.yml
 
 
-Step 3 --- ingest repositories
+Step 4 --- ingest repositories
 ------------------------------
 
 You are now ready to ingest your first repository into your local Software
@@ -207,7 +204,7 @@ only *new* objects added since the previous visit will be archived upon the
 next one.
 
 
-Step 4 --- browse the archive
+Step 5 --- browse the archive
 -----------------------------
 
 You can now setup a local web app to browse what you have locally archived. The

[Phabricator Migration user]

Some references in the commit message have been migrated:

• D430 is now !2 (closed)