Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Docs: Update instructions for local deployment to use aiidalab-launch. #256

Merged
merged 1 commit into from
Jan 21, 2022
Merged

Docs: Update instructions for local deployment to use aiidalab-launch. #256

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 26 additions & 25 deletions docs/source/usage/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,51 +18,52 @@ As a user, you have three options to access AiiDAlab:
Run AiiDAlab locally
====================

Prerequisites
-------------
To run AiiDAlab on your own workstation or laptop you can either

Linux or MacOS with `Docker installed <https://www.docker.com/get-started>`__
- run the image directly with: ```docker run aiidalab-docker-stack -p 8888:8888```, or
- *(recommended)* use the :ref:`aiidalab-launch <usage:aiidalab-launch>` tool which is a thin docker wrapper.

.. _usage:aiidalab-launch:

Instructions
------------
AiiDAlab Launch
---------------

Pull the AiiDAlab docker image from DockerHub and tag it so that the startup script recognizes it:
To use AiiDAlab launch you will have to

.. code-block:: console

$ docker pull aiidalab/aiidalab-docker-stack:latest
$ docker tag aiidalab/aiidalab-docker-stack:latest aiidalab-docker-stack:develop

Clone the `AiiDAlab Docker Stack <https://github.com/aiidalab/aiidalab-docker-stack>`__ repository and enter the cloned directory:
#. `Install Docker on your workstation or laptop. <https://docs.docker.com/get-docker/>`_
#. Install AiiDAlab launch with `pipx <https://pypa.github.io/pipx/installation/>`_ (**recommended**):

.. code-block:: console

$ git clone https://github.com/aiidalab/aiidalab-docker-stack
$ cd aiidalab-docker-stack
pipx install aiidalab-launch

Start AiiDAlab by running:
Or directly with pip (``pip install aiidalab-launch``).

#. Start AiiDAlab with

.. code-block:: console

$ ./run.sh --no-build 8888 ~/aiidalab
aiidalab-launch start

#. Follow the instructions on screen to open AiiDAlab in the browser.

See ``aiidalab-launch --help`` for detailed help.

* ``8888`` is the port under which the AiiDAlab web interface will be available.
* ``~/aiidalab`` is the **absolute** path to the directory that will be mounted as the persistent home directory inside the container.
If the directory does not exist, it will be created.
Instance Management
^^^^^^^^^^^^^^^^^^^

The startup procedure can take a while, particularly when you run it for the first time.
Once it is done, open the link provided at the bottom of the console in your web browser.
You should now see the AiiDAlab home page.
You can inspect the status of all configured AiiDAlab profiles with:

.. note::
.. code-block:: console

The instructions above use the pre-built AiiDAlab docker image from DockerHub.
In order to build the image yourself (e.g. to apply modifications), simply run the script without the ``--no-build`` option::
aiidalab-launch status

./run.sh 8888 ~/aiidalab
Profile Management
^^^^^^^^^^^^^^^^^^

The tool allows to manage multiple profiles, e.g., with different home directories or ports.
See ``aiidalab-launch profiles --help`` for more information.

******************
AiiDAlab Home page
Expand Down