Skip to content

Commit

Permalink
docs: minor improvements for local deployment guide (#262)
Browse files Browse the repository at this point in the history
* docs: minor improvements for local deployment guide

Signed-off-by: SdgJlbl <sarah.diot-girard@owkin.com>

* Remove instructions for local installation of the frontend (with npm)

Signed-off-by: SdgJlbl <sarah.diot-girard@owkin.com>

* Upgrade minimal Skaffold version

Signed-off-by: SdgJlbl <sarah.diot-girard@owkin.com>

---------

Signed-off-by: SdgJlbl <sarah.diot-girard@owkin.com>
  • Loading branch information
SdgJlbl authored Feb 1, 2023
1 parent 139afeb commit fc74ac1
Showing 1 changed file with 26 additions and 43 deletions.
69 changes: 26 additions & 43 deletions docs/source/contributing/local-deployment.rst
Original file line number Diff line number Diff line change
Expand Up @@ -29,16 +29,19 @@ The following table indicates the resources needed to run the Substra stack loca
- RAM
* - Minimal
- 2 cores
- 35 GB
- 4 GB
- 70 GB
- 10 GB
* - Recommended
- 4-8 cores
- 50 GB
- 100 GB
- 16 GB

.. caution::
Choose wisely the parameters passed to Kubernetes as it might try to use all the allocated resources without regards for your system.

.. caution::
Check that enough available disk space is allocated to Docker, else you might run into errors.

Software
--------

Expand All @@ -51,9 +54,8 @@ Software

* k3d/k3s (>= 5.0.0)
* `kubectl <https://kubernetes.io/>`_
* `Skaffold <https://skaffold.dev/>`_
* `Skaffold <https://skaffold.dev/>`_ (>= 2.1.0)
* `Helm 3 <https://helm.sh/>`_ (>= 3.7.0)
* `nodeJS <https://nodejs.org/>`_ (== 16.13.0)

Instructions for Mac
^^^^^^^^^^^^^^^^^^^^
Expand Down Expand Up @@ -124,15 +126,7 @@ First time configuration
git clone https://github.com/Substra/substra-frontend.git
5. Install frontend dependencies

.. code-block:: bash
cd substra-frontend
npm install --dev
6. Update Helm charts
5. Update Helm charts

.. code-block:: bash
Expand Down Expand Up @@ -169,32 +163,28 @@ Launching
skaffold run -p dev,arm64
.. tip::
If you need to re-run `skaffold run` for whatever reason, don't forget to use `skaffold delete` to reset the state beforehand (or reset your environment by running the `k3-create.sh` script again).

.. tip::
When re-launching the orchestrator and the backend, you can speed up the processing by avoiding the update of the chart dependencies using the profile ``nodeps``.

.. code-block:: bash
skaffold run -p nodeps
* Deploy the frontend. You can use two methods (described below)

a. Local server: Execute the following command:
* Deploy the frontend

.. code-block:: bash
cd substra-frontend
API_URL=http://substra-backend.org-1.com npm run dev
b. Docker:

.. code-block:: bash
.. code-block:: bash
docker build -f docker/substra-frontend/Dockerfile --target dev -t substra-frontend .
docker run -it --rm -p 3000:3000 --name DOCKER_FRONTEND_CONTAINER_NAME -e API_URL=http://substra-backend.org-1.com -v ${PWD}/src:/workspace/src substra-frontend
cd substra-frontend
docker build -f docker/substra-frontend/Dockerfile --target dev -t substra-frontend .
docker run -it --rm -p 3000:3000 -e API_URL=http://substra-backend.org-1.com -v ${PWD}/src:/workspace/src substra-frontend
| with ``DOCKER_FRONTEND_CONTAINER_NAME`` the name of the frontend container that will be used for the rest of the operations.
You can access the frontend at http://substra-frontend.org-1.com:3000/. The dev credentials are:

* In both case, you can access the frontend at http://substra-frontend.org-1.com:3000/.
* login: ``org-1``
* password: ``p@sswr0d44``

Monitoring
==========
Expand All @@ -206,16 +196,8 @@ Stopping

To stop the Substra stack, you need to stop the 3 components (backend, orchestrator and frontend) individually.

* Stop the frontend: This action depends on which option you chose during the launch:

a. Local server: Stop the process running the local server (usually using *Control+C* or *Command+C* on macOS)
b. Docker:

.. code-block:: bash
docker stop DOCKER_FRONTEND_CONTAINER_NAME
* Stop the frontend: Stop the process running the local server in Docker (using *Control+C*)

| with ``DOCKER_FRONTEND_CONTAINER_NAME`` the name of the frontend container you chose during the launch
* Stop the orchestrator:

.. code-block:: bash
Expand All @@ -234,7 +216,7 @@ If this command fails and you still have pods up, you can use the following comm

.. code-block:: bash
kubectl rm ns org-1 org-2
kubectl delete ns org-1 org-2
Next steps
==========
Expand Down Expand Up @@ -304,14 +286,15 @@ The following list describes errors that have already occurred, and their resolu
Troubleshooting deployment
--------------------------

Skaffold version 1.31.0
^^^^^^^^^^^^^^^^^^^^^^^
Skaffold version
^^^^^^^^^^^^^^^^

Due to a change in the deployment sequence in Skaffold 1.31.x our components cannot be deployed with this version using only ``skaffold run``. Either upgrade to `Skaffold 1.32.0 <https://github.com/GoogleContainerTools/skaffold/releases/tag/v1.32.0>`__ or add the ``--status-check=false`` flag.
Skaffold schemas have some incompatibilities between version `1.x` and version `2.0`. Check your version number and upgrade to Skaffold v2 (2.1.0 recommended) if necessary.

.. code-block:: bash
skaffold dev/run/deploy --status-check=false
skaffold version
brew upgrade skaffold
Other errors during backend deployment
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Expand Down

0 comments on commit fc74ac1

Please sign in to comment.