Improve README

README.adoc

@@ -45,7 +45,7 @@ _Simplestblog_ is an extremely simple blog web application written in Python usi
 
 == Install, configure and run
 
-You can install and run the service without or with Docker/Podman.
+You can install and run the service without or with Docker/Podman, but in both cases you need to provide a configuration file.
 
 === Configuration options
 
@@ -133,7 +133,7 @@ $ SIMPLESTBLOG_SETTINGS_FILE=<path_to_configuration> flask --app simplestblog ru
 
 with `<path_to_configuration>` a valid path to a configuration file for the application.
 
-The application always listens on port 5000, therefore you should be able to access it on http://localhost:5000.
+The application listens on port 5000, therefore you should be able to access it locally on http://localhost:5000.
 
 === Install and run with Docker/Podman
 
@@ -146,6 +146,7 @@ Note that the provided Docker/Podman image pre-sets the `SIMPLESTBLOG_SETTINGS_F
 
 
 To initialize the database:
+
 ```
 $ podman run -v <path_to_configuration>:/config.py  docker-registry.univ-nantes.fr/dde/simplestblog:latest flask --app simplestblog init-db
 ```
@@ -155,9 +156,11 @@ with `<path_to_configuration>` a valid path to a configuration file for the appl
 ==== Run
 
 To run the application:
+
 ```
 $ podman run -v <path_to_configuration>:/config.py -p 5000:5000 docker-registry.univ-nantes.fr/dde/simplestblog:latest flask --app simplestblog run
 ```
+
 with `<path_to_configuration>` a valid path to a configuration file for the application.
 
 You should be able to access it on http://localhost:5000.
@@ -171,11 +174,11 @@ We explain in this part how to setup a development environment for working on si
 
 ==== Get the code and download dependencies
 
-Clone the repository and visit the `application` folder:
+Clone the repository and visit the folder:
 
 ....
 $ git clone https://gitlab.univ-nantes.fr/dde/simplestblog
-$ cd simplestblog/application
+$ cd simplestblog
 ....
 
 Create a _venv_ in the folder and activate it:
@@ -185,11 +188,12 @@ $ python -m venv .venv
 $ source .venv/bin/activate
 ....
 
-NOTE: All following commands assume we have already activate the _venv_.
+NOTE: All following commands assume we have already activated the _venv_.
 
-Install dependencies:
+Go in the `application` folder and install dependencies:
 
 ....
+$ cd application
 $ pip install -e .
 ....
 
@@ -198,8 +202,8 @@ $ pip install -e .
 The application can recognize the environment variable `SIMPLESTBLOG_DEV_MODE` to start in "development mode".
 When in this mode, the application:
 
-- Use a dummy constant `SECRET_KEY`,
-- Use a local SQLite database created in an `instance` folder.
+- Use a dummy constant in the `SECRET_KEY` variable,
+- Use a local SQLite database created in a local `instance` folder.
 
 To initialize an empty database in "development mode" :
 ....
@@ -211,15 +215,16 @@ Start the application in "development mode" :
 $ SIMPLESTBLOG_DEV_MODE="true" flask --app simplestblog run --debug
 ....
 
-Open http://127.0.0.1:5000 in a browser and start coding and debugging!
+Open http://localhost:5000 in a browser and start coding and debugging!
 
 
 ==== Run unit test cases
 
-A https://docs.pytest.org/en/7.4.x/[pytest] test suite is available in the `tests` folder.
+A https://docs.pytest.org/[pytest] test suite is available in the `tests` folder.
 
 First install dependencies:
 ....
+$ cd application
 $ pip install '.[test]'
 ....
 
@@ -244,6 +249,7 @@ Static analysis can be run using https://flake8.pycqa.org/en/latest/[Flake8].
 
 First install dependencies:
 ....
+$ cd application
 $ pip install '.[static-analysis]'
 ....
 
@@ -252,15 +258,17 @@ Then run the analyzer with default options on both source folders:
 $ flake8 simplestblog tests
 ....
 
-Th report is available directly as output in the terminal. If it is empty, no problem has been detected.
+Th report is available directly as output in the terminal. 
+If it is empty, no problem has been detected.
 
 ==== Build the Docker/Podman image
 
-A `Dockerfile` can be used to build and package the application as a Docker/Podman image.
+A `Dockerfile` is provided and can be used to build and package the application as a Docker/Podman image.
 
 Example of building the image with https://podman.io/[Podman]:
 
 ....
+$ cd application
 $ podman build -t simplestblog-dev .
 ....
 
@@ -273,7 +281,7 @@ See the `.gitlab-ci.yml` file for more information.
 
 == Deployment
 
-The `deployment` folder contains an Ansible project to deploy the application on existing infrastructure.
+The `deployment` folder contains an Ansible project to deploy the application in "production mode" on existing infrastructure.
 
 Deployment is achieved using two Jinja templates:
 - `templates/config.py.j2` is a configuration file for the application targeting a MySQL-compatible database.
@@ -289,11 +297,25 @@ Three Ansible playbooks are provided:
 - `service-down.playbook.yml`: stop and delete the containers.
 - `init-db.playbook.yml`: initialize the database − must be executed once the application is already up and running.
 
+To deploy the application for the first time, first verify that the inventory contains the right information, then run:
+
+```
+$ ansible-playbook -i inventory init-db.playbook.yml
+$ ansible-playbook -i inventory service-up.playbook.yml
+```
+
+To remove the application:
+
+```
+$ ansible-playbook -i inventory service-down.playbook.yml
+```
+
+
 [NOTE]
 ====
 This Ansible project assumes that infrastructure is already available, and that each target host satisfy the following requirements:
 
-- Run a Linux distribution,
+- Runs a Linux system with an SSH access,
 - Has Podman and podman-compose installed.
 ====