Skip to content

Commit 17ad32c

Browse files
committed
docs-reorg: refactor Install section into Get started
1 parent 3522c53 commit 17ad32c

22 files changed

+470
-401
lines changed

docs/community/code/package-development.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ editable install of the Python package:
1616
!!! note
1717

1818
``mkvirtualenv`` is a tool provided by virtualenv-wrapper to manage Python
19-
virtualenvs. See [Python virtual environments](../../install/virtualenvs.md)
19+
virtualenvs. See [Python virtual environments](../../reference/virtualenvs.md)
2020

2121
```bash
2222
cd ~/src/invenio-app-rdm

docs/install/build-setup-run.md

Lines changed: 94 additions & 79 deletions
Original file line numberDiff line numberDiff line change
@@ -1,42 +1,45 @@
11
# Build, setup and run
22

3-
Now, that we have created a project folder, we need to build and set up the InvenioRDM application.
3+
Now that we have created a project folder, we need to build and set up the InvenioRDM application.
44

5-
The application can be built and installed in two different ways:
5+
As mentioned before, the application can be built and installed in two different ways:
66

7-
- Local (good for developers or for customizing your instance): The application is installed locally on your machine in a Python virtual environment managed by the ``pipenv`` tool.
8-
- Container (good for quick preview): The application is built inside a Docker image.
7+
- *Local development* (good for developers or for customizing your instance): The application is installed directly on your machine in a Python [virtual environment](../reference/virtualenvs.md) managed by the ``pipenv`` tool (its services are containerized though).
8+
- *Containerized preview* (good for quick preview): The application is built inside a Docker image and, it, along with the services are all containerized.
99

10-
## For the impatient
10+
## Condensed version
1111

1212
For the impatient, here are the commands to build, setup and run InvenioRDM. For clarity, we have decomposed them into individual steps in the guide below. Follow the guide below for step-by-step details:
1313

14-
Container:
14+
=== "Local development"
1515

16-
```bash
17-
invenio-cli containers start --lock --build --setup
18-
```
16+
```shell
17+
# Install Python and Javascript packages
18+
invenio-cli install
19+
# Set up containerized database, cache, OpenSearch, etc.
20+
invenio-cli services setup
21+
# Serve the application locally through a development server
22+
invenio-cli run
23+
```
1924

20-
Local:
25+
=== "Containerized preview"
2126

22-
```bash
23-
invenio-cli install
24-
invenio-cli services setup
25-
invenio-cli run
26-
```
27+
```shell
28+
invenio-cli containers start --lock --build --setup
29+
```
2730

2831
!!! info
29-
If you run the above commands, you're all set for this section. If you like to learn more about the build process,
32+
If you run the above commands, you're all set for this section. If you would like to learn more about the build process,
3033
then follow the steps below instead.
3134

3235

3336
## Python dependencies
3437

3538
First, we start by locking the Python dependencies, which ensures that you will always have the same versions of dependencies if you reinstall in the future. Locked dependencies are important for having reproducible installs.
3639

37-
This step will normally be executed automatically by both the local and container installation options, but here we run it explicitly.
40+
This step is executed automatically by both the local development (under `invenio-cli install`) and containerized preview (`--lock` option) installation options, but here we run it explicitly.
3841

39-
Let's try it:
42+
It's the same command for either installation option. Let's try it:
4043

4144
```bash
4245
cd my-site/
@@ -70,49 +73,43 @@ Dependencies locked successfully.
7073

7174
A new file ``Pipfile.lock`` has now been created with the locked dependencies.
7275

73-
Next, choose option 1 or option 2 for your preferred installation method.
76+
Next, follow the *local development* option or *containerized preview* option according to your preferred installation method.
7477

75-
## Option 1: Container install
78+
## Local development option
7679

77-
The container install is good for a quick preview, or if you don't want all dependencies locally. It is not good for development or for customizing your instance, as it requires you to rebuild the Docker image for every change which can be time consuming.
80+
The local install is good for developers or if you like to customize InvenioRDM as it avoids the waiting time for building a new Docker image. For instance, changing the layout will be much faster with a local install.
7881

7982
### Build
8083

81-
For the container build, you first build the Docker application image using
82-
the following command:
84+
The local build steps involve installing all the Python dependencies into a local Python virtual environment, as well as all the Javascript dependencies. The Javascript dependencies are defined in the Python packages. This is done with the command:
8385

8486
```bash
85-
invenio-cli containers build
87+
invenio-cli install
8688
```
8789
```console
88-
Building images... Pull newer versions True, use cache True
89-
Checking if dependencies are locked.
90-
Dependencies are locked
91-
Building images...
90+
Installing python dependencies... Please be patient, this operation might take some time...
91+
Installing dependencies from Pipfile.lock (271a6d)…
92+
🐍 ▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉ 200/200 — 00:02:00
9293

9394
[...]
9495

95-
Successfully built f1fc95ce1037
96-
Successfully tagged my-site:latest
97-
Images built successfully.
96+
Built webpack project.
97+
Assets and statics updated.
98+
Dependencies installed successfully.
9899
```
99100

100-
The command will:
101+
The command does the following:
101102

102-
- Download the Docker images for the services (database, cache, search engine, etc.)
103-
- Build the Docker image for the InvenioRDM application using the ``Dockerfile`` in your project.
104103
- Install Python dependencies (according the ``Pipfile.lock``)
105104
- Install JavaScript dependencies
106105
- Build the JavaScript/CSS web assets
107106

108107
### Setup
109108

110-
Once the Docker application image has been built, we need to initialize the database, the indices and so on. For this, we use again the ``containers`` command.
111-
112-
The first time this command is run, the services will be setup correctly and the containers running them will even restart upon a reboot of your machine. If you stop and restart those containers, your data will still be there. Upon running this command again, the initial setup is skipped.
109+
We need to initialize the database, the indices and so on. For this, we use the services command. The first time this command is run, the services will be setup correctly and the containers running them will even restart upon a reboot of your machine. If you stop and restart those containers, your data will still be there. Upon running this command again, the initial setup is skipped.
113110

114111
```bash
115-
invenio-cli containers setup
112+
invenio-cli services setup
116113
```
117114
```console
118115
Making sure containers are up...
@@ -132,71 +129,83 @@ Creating indexes...
132129
Putting templates...
133130
```
134131

135-
The command will:
136-
137-
- Create the database and Elasticsearch indexes.
138-
- Load fixtures data into InvenioRDM.
139-
- Create demo records.
140-
141132
!!! tip
142133

143134
You can skip the creation of demo records by using the ``--no-demo-data`` option (``-N`` for short):
144135

136+
```shell
137+
invenio-cli services setup --no-demo-data
145138
```
146-
invenio-cli containers setup --no-demo-data
139+
140+
You can forcefully redo the setup step with the ``--force`` option (``-f`` for short):
141+
142+
```shell
143+
invenio-cli services setup --force
147144
```
148145

149146
### Run
150147

151-
You can now run the application container and related services:
148+
You can now run the application locally:
152149

153150
```bash
154-
invenio-cli containers start
151+
invenio-cli run
155152
```
156153

157-
Go and explore your InvenioRDM instance at [https://127.0.0.1](https://127.0.0.1).
154+
Go and explore your InvenioRDM instance at [https://127.0.0.1:5000](https://127.0.0.1:5000). This is the default host and port configured in ``invenio.cfg``.
158155

159-
!!! warning "Visit 127.0.0.1, not localhost"
160-
Due to Content Security Policy (CSP) headers it is important that you visit ``127.0.0.1``, and not ``localhost`` unless you set ``INVENIO_SITE_UI_URL`` and ``INVENIO_SITE_API_URL`` to ``https://localhost`` and ``https://localhost/api`` respectively.
161156

162-
!!! tip
163-
You can provide other configuration variables by setting them as environment variables with the ``INVENIO_`` prefix.
157+
!!! tip "Change the host and port"
158+
By default, the host is `127.0.0.1` and the port is `5000`. Pass `--host` and `--port`
159+
to change them:
164160

165-
## Option 2: Local install
161+
`invenio-cli run --host 0.0.0.0 --port 443`
166162

167-
The local install is good for developers or if you like to customize InvenioRDM as it avoids the waiting time for building a new Docker image. For instance, changing the layout will be much faster with a local install.
163+
It's a development server though, so don't use it for production.
164+
165+
!!! warning "Visit 127.0.0.1, not localhost"
166+
Due to Content Security Policy (CSP) headers it is important that you use ``127.0.0.1``, and not ``localhost``.
167+
168+
## Containerized preview option
169+
170+
The container install is good for a quick preview, or if you don't want all dependencies locally. It is not good for development or for customizing your instance, as it requires you to rebuild the Docker image for every change which can be time consuming.
168171

169172
### Build
170173

171-
The local build steps involve installing all the Python dependencies into a local Python virtual environment. This is done with the command (the virtualenv is managed by ``pipenv``):
174+
For the container build, you first build the Docker application image using
175+
the following command:
172176

173177
```bash
174-
invenio-cli install
178+
invenio-cli containers build
175179
```
176180
```console
177-
Installing python dependencies... Please be patient, this operation might take some time...
178-
Installing dependencies from Pipfile.lock (271a6d)…
179-
🐍 ▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉ 200/200 — 00:02:00
181+
Building images... Pull newer versions True, use cache True
182+
Checking if dependencies are locked.
183+
Dependencies are locked
184+
Building images...
180185

181186
[...]
182187

183-
Built webpack project.
184-
Assets and statics updated.
185-
Dependencies installed successfully.
188+
Successfully built f1fc95ce1037
189+
Successfully tagged my-site:latest
190+
Images built successfully.
186191
```
187192

188-
Similar to the ``containers`` command, the command does the following:
193+
The command will:
189194

195+
- Download the Docker images for the services (database, cache, search engine, etc.)
196+
- Build the Docker image for the InvenioRDM application using the ``Dockerfile`` in your project.
190197
- Install Python dependencies (according the ``Pipfile.lock``)
191198
- Install JavaScript dependencies
192199
- Build the JavaScript/CSS web assets
193200

194201
### Setup
195202

196-
We need to initialize the database, the indices and so on. For this, we use the services command. The first time this command is run, the services will be setup correctly and the containers running them will even restart upon a reboot of your machine. If you stop and restart those containers, your data will still be there. Upon running this command again, the initial setup is skipped.
203+
Once the Docker application image has been built, we need to initialize the database, the indices and so on. For this, we use again the ``containers`` command.
204+
205+
The first time this command is run, the services will be setup correctly and the containers running them will even restart upon a reboot of your machine. If you stop and restart those containers, your data will still be there. Upon running this command again, the initial setup is skipped.
197206

198207
```bash
199-
invenio-cli services setup
208+
invenio-cli containers setup
200209
```
201210
```console
202211
Making sure containers are up...
@@ -216,35 +225,41 @@ Creating indexes...
216225
Putting templates...
217226
```
218227

228+
The command will:
229+
230+
- Create the database and Elasticsearch indexes.
231+
- Load fixtures data into InvenioRDM.
232+
- Create demo records.
233+
219234
!!! tip
220235

221236
You can skip the creation of demo records by using the ``--no-demo-data`` option (``-N`` for short):
222237

223-
```
224-
invenio-cli services setup --no-demo-data
238+
```shell
239+
invenio-cli containers setup --no-demo-data
225240
```
226241

242+
You can forcefully redo the setup step with the ``--force`` option (``-f`` for short):
243+
244+
```shell
245+
invenio-cli containers setup --force
246+
```
227247

228248
### Run
229249

230-
You can now run the application locally:
250+
You can now run the application container and related services:
231251

232252
```bash
233-
invenio-cli run
253+
invenio-cli containers start
234254
```
235255

236-
Go and explore your InvenioRDM instance at [https://127.0.0.1:5000](https://127.0.0.1:5000). This is the default host and port configured in ``invenio.cfg``.
237-
238-
!!! warning "Visit 127.0.0.1, not localhost"
239-
Due to Content Security Policy (CSP) headers it is important that you use ``127.0.0.1``, and not ``localhost``.
240-
241-
!!! tip "Change the host and port"
242-
By default, the host is `127.0.0.1` and the port is `5000`. Pass `--host` and `--port`
243-
to change them e.g.:
256+
Go and explore your InvenioRDM instance at [https://127.0.0.1](https://127.0.0.1).
244257

245-
`invenio-cli run --host 0.0.0.0 --port 443`
258+
!!! tip
259+
You can provide other configuration variables by setting them as environment variables with the ``INVENIO_`` prefix.
246260

247-
It's a development server, so don't use it for production.
261+
!!! warning "Visit 127.0.0.1, not localhost"
262+
Due to Content Security Policy (CSP) headers it is important that you visit ``127.0.0.1``, and not ``localhost`` unless you set ``INVENIO_SITE_UI_URL`` and ``INVENIO_SITE_API_URL`` to ``https://localhost`` and ``https://localhost/api`` respectively.
248263

249264
## Troubleshooting
250265

docs/install/cli.md

Lines changed: 21 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,39 +1,41 @@
1-
# Install CLI
1+
# Install the command line tool
22

3-
InvenioRDM comes with a CLI management tool called Invenio-CLI which is used to manage and work with your local installation.
3+
InvenioRDM is set up with a command line management tool, `invenio-cli`, which is used to manage and work with your local installation.
44

5-
You can install the Invenio CLI package named `invenio-cli`. The package is available on [PyPI](https://pypi.org/project/invenio-cli/). Use your favorite way to install a Python package:
5+
## Installation
66

7-
Via pip:
7+
`invenio-cli` is available on [PyPI](https://pypi.org/project/invenio-cli/). Use your favorite way to install it:
88

9-
```bash
10-
pip install invenio-cli
11-
```
9+
=== "pip"
1210

13-
Via pipenv:
11+
```shell
12+
pip install invenio-cli
13+
```
1414

15-
```bash
16-
pipenv install invenio-cli
17-
```
15+
=== "uv"
1816

19-
Via pipx:
17+
```shell
18+
uv tool install invenio-cli
19+
```
2020

21-
```bash
22-
pipx install invenio-cli
23-
```
21+
=== "pipx"
22+
23+
```shell
24+
pipx install invenio-cli
25+
```
2426

25-
To make sure you've installed successfully:
27+
To make sure you've installed it successfully:
2628

2729
```bash
2830
invenio-cli --version
2931
```
3032

31-
You'll find the latest released version number on [PyPi](https://pypi.org/project/invenio-cli/).
33+
You'll find the latest released version number on [PyPi](https://pypi.org/project/invenio-cli/). Each new version of InvenioRDM is accompanied by a new version of `invenio-cli` if only to have it select the new version as the default when initializing a project.
3234

33-
### Commands reference
35+
## Commands reference
3436

3537
For a full reference of available commands, see the [CLI reference](../reference/cli.md)
3638

3739

3840
!!! tip "Shell tab completion"
39-
Invenio-CLI has support for Shell tab completion of commands. See [Shell completion](../reference/cli.md#shell-completion).
41+
`invenio-cli` has support for shell tab completion of commands. See [shell completion](../reference/cli.md#shell-completion).

0 commit comments

Comments
 (0)