From 58005f75181c27cd84aaca029c04c72ca0de307e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Karl-Ulrich=20Kr=C3=A4gelin?= Date: Fri, 9 Aug 2024 07:59:17 +0200 Subject: [PATCH 1/2] add devbox installation docs --- docs/install/devbox.md | 54 ++++++++++++++++++++++++++++++++++++++++++ docs/install/index.md | 5 ++++ mkdocs.yml | 1 + 3 files changed, 60 insertions(+) create mode 100644 docs/install/devbox.md diff --git a/docs/install/devbox.md b/docs/install/devbox.md new file mode 100644 index 00000000..caf81ce9 --- /dev/null +++ b/docs/install/devbox.md @@ -0,0 +1,54 @@ +# Installation using Devbox + +An alternative to the manual local install or the containerized installation is installing InvenioRDM locally with the tool [Devbox](https://www.jetify.com/devbox/). + +It provides a standardized way of installation that can be shared with other developers while still allowing easy access to and modification of local files. + +More information on Devbox and InvenioRDM can be found in [this presentation](https://zenodo.org/records/12554567) from the Open Repositories 2024 conference. + +Devbox uses the Nix package manager to provide the user with encapsulated shell sessions that handle their own system package dependencies (so ypu can have for example a python and a node version living only in a devbox environment, not polluting you system outside of it). + +!!! info "Information" + + The main difference between this method and the manual install is that you let nix manage the dependencies for you - no need to use pyenv or nvm to manage python versions for example. The provided installation script is just a small extra to make the installation even easier but it is not obligatory to use. + +## Preparation + +- On your machine you will need to install **Docker** and **Devbox** (as well as `git`): + - Please read the [system requirements for Docker](https://inveniordm.docs.cern.ch/install/requirements/#docker) of InvenioRDM! + - You can find the current Devbox installation guide [here](https://www.jetify.com/devbox/docs/installing_devbox/). +- Clone the [invenio-devbox repository](https://github.com/ulbmuenster/invenio-devbox) to your lcoal machine. It contains a pre-configured installation script that can later be adapted to match your instance's needs. This includes installation of the Invenio CLI tool and scaffolding of the project. + +## Devbox installation + +- Navigate to the invenio-devbox directory that you just cloned: + - e.g. + ``` + cd $HOME/invenio_devbox + ``` +- Start the Devbox shell: + ``` + devbox shell + ``` +- Install a fresh InvenioRDM instance with the [provided installation script](https://github.com/ulbmuenster/invenio-devbox/blob/main/devbox_scripts/install-empty.sh) that is using `invenio-cli` to set up the instance: + ``` + devbox run install-empty + ``` + - You will be prompted to enter a name for your new instance or accept the default *my-site* + - Choosing a custom name that contains a dash (e.g. `test-instance`) leads to an error and should therefore be avoided. +- Navigate to your instance directory, e.g.: + ``` + cd my-site + ``` +- Start your new InvenioRDM instance: + ``` + invenio-cli run + ``` +- Open your browser and navigate to `https://127.0.0.1:5000` + - Click the button for “Advanced…” options and click “Accept the risk and continue” + - See the [notes in the Quick Start guide](https://inveniordm.docs.cern.ch/install/#5-explore-inveniordm) on why this is necessary. +- You can log in with the already activated admin account: + - user: `admin@inveniosoftware.org` with password: `123456` +- Enjoy your fresh InvenioRDM installation! + +The Devbox installation will behave like a local installation, so you can edit files easily and customize the instance to meet your requirements. You do not need to create or activate an admin account - this was already done by the installation script. Any other manual steps that apply to your installation can be added to this script as well, so you don't have to configure anything else after running it. diff --git a/docs/install/index.md b/docs/install/index.md index de7e2513..2a143893 100644 --- a/docs/install/index.md +++ b/docs/install/index.md @@ -8,6 +8,11 @@ The guide is intended for system administrators and developers who want to try, This guide covers how to install InvenioRDM locally on your machine, how to set up and configure your system for InvenioRDM. +!!! info "Alternative Installation Method using [Devbox](https://www.jetify.com/devbox/)" + + If you are interested in an alternative installation approach that requires fewer manual steps + you are welcome to check out [Devbox](devbox.md) + ## Quick start #### [1. Install CLI tool](cli.md) diff --git a/mkdocs.yml b/mkdocs.yml index 6e24705c..dc5f01e0 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -57,6 +57,7 @@ nav: - Access requests: "features/features-walk-through/access_requests.md" - Install: - Quick start: "install/index.md" + - Devbox: "install/devbox.md" - System requirements: "install/requirements.md" - Install CLI: "install/cli.md" - Scaffold: "install/scaffold.md" From 4032b4235ca401f66b7fe5d17f85cba97453dedd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Karl-Ulrich=20Kr=C3=A4gelin?= Date: Mon, 12 Aug 2024 10:00:03 +0200 Subject: [PATCH 2/2] fix typos --- docs/install/devbox.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/install/devbox.md b/docs/install/devbox.md index caf81ce9..b30db0ea 100644 --- a/docs/install/devbox.md +++ b/docs/install/devbox.md @@ -6,18 +6,18 @@ It provides a standardized way of installation that can be shared with other dev More information on Devbox and InvenioRDM can be found in [this presentation](https://zenodo.org/records/12554567) from the Open Repositories 2024 conference. -Devbox uses the Nix package manager to provide the user with encapsulated shell sessions that handle their own system package dependencies (so ypu can have for example a python and a node version living only in a devbox environment, not polluting you system outside of it). +Devbox uses the Nix package manager to provide the user with encapsulated shell sessions that handle their own system package dependencies (so you can have for example a Python and a node version living only in a devbox environment, not polluting your system outside of it). !!! info "Information" - The main difference between this method and the manual install is that you let nix manage the dependencies for you - no need to use pyenv or nvm to manage python versions for example. The provided installation script is just a small extra to make the installation even easier but it is not obligatory to use. + The main difference between this method and the manual installation method is that you let `nix` manage the dependencies for you - no need to use `pyenv` or `nvm` to manage Python or Node versions for example. The provided installation script is just a small extra to make the installation even easier but it is not obligatory to use. ## Preparation - On your machine you will need to install **Docker** and **Devbox** (as well as `git`): - Please read the [system requirements for Docker](https://inveniordm.docs.cern.ch/install/requirements/#docker) of InvenioRDM! - You can find the current Devbox installation guide [here](https://www.jetify.com/devbox/docs/installing_devbox/). -- Clone the [invenio-devbox repository](https://github.com/ulbmuenster/invenio-devbox) to your lcoal machine. It contains a pre-configured installation script that can later be adapted to match your instance's needs. This includes installation of the Invenio CLI tool and scaffolding of the project. +- Clone the [invenio-devbox repository](https://github.com/ulbmuenster/invenio-devbox) to your lcoal machine. It contains a pre-configured installation script that can later be adapted to match your instance's needs. This includes the installation of the Invenio CLI tool and the scaffolding of the project. ## Devbox installation @@ -30,7 +30,7 @@ Devbox uses the Nix package manager to provide the user with encapsulated shell ``` devbox shell ``` -- Install a fresh InvenioRDM instance with the [provided installation script](https://github.com/ulbmuenster/invenio-devbox/blob/main/devbox_scripts/install-empty.sh) that is using `invenio-cli` to set up the instance: +- Install a fresh InvenioRDM instance with the [provided installation script](https://github.com/ulbmuenster/invenio-devbox/blob/main/devbox_scripts/install-empty.sh) which is using `invenio-cli` to set up the instance: ``` devbox run install-empty ```