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

Refined instructions for local installation setup #38

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Refined instructions for local installation setup #38

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9a1820e
Refined instructions for local installation setup
kdaud Mar 5, 2023
5950252
Refine recommendation for linux users
kdaud Mar 6, 2023
3d99fa0
Add a prerequisite section in the README.md
kdaud Mar 15, 2023
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
34 changes: 28 additions & 6 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ mkdir $BAHMNI_DIR
### Download the Docker Compose project itself:

```
export VERSION=2.0.0-SNAPSHOT && \
export VERSION=2.4.0-SNAPSHOT && \
# Download the project && \
mvn org.apache.maven.plugins:maven-dependency-plugin:3.2.0:get -DremoteRepositories=https://nexus.mekomsolutions.net/repository/maven-public -Dartifact=net.mekomsolutions:bahmni-docker-compose:$VERSION:zip -Dtransitive=false --legacy-local-repository && \
# Unzip the project in $BAHMNI_DIR/bahmni-docker-compose-$VERSION && \
Expand All @@ -41,7 +41,7 @@ Fetch the distribution of your choice:
Eg, Bahmni Distro **Haiti**:
```
export DISTRO_GROUP="haiti" && \
export DISTRO_VERSION="1.2.0-SNAPSHOT" && \
export DISTRO_VERSION="2.4.0" && \
# Download the distro && \
mvn org.apache.maven.plugins:maven-dependency-plugin:3.2.0:get -DremoteRepositories=https://nexus.mekomsolutions.net/repository/maven-public -Dartifact=net.mekomsolutions:bahmni-distro-$DISTRO_GROUP:$DISTRO_VERSION:zip -Dtransitive=false --legacy-local-repository && \
# Unzip the distro in $BAHMNI_DIR/bahmni-distro-$DISTRO_GROUP-$DISTRO_VERSION && \
Expand All @@ -64,18 +64,40 @@ export EIP_CONFIG_PATH=$DISTRO_PATH/eip_config

The complete list of available variables can be found in [.env](.env).

### Move to the location of bahmni-docker-compose project

```bash
cd $BAHMNI_DIR/bahmni-docker-compose-$VERSION
```

### Start Bahmni:

<table>
<tr>
<td> macOS </td> <td> Linux </td>
</tr>
<tr>
<td>

```bash
docker compose -p $DISTRO_GROUP up
```
cd $BAHMNI_DIR/bahmni-docker-compose-$VERSION && \
docker-compose -p $DISTRO_GROUP up

</td>
<td>

```bash
sudo -E docker compose -p $DISTRO_GROUP up
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well... If correctly set up Docker should run without sudo.
In general, we never see instructions run with sudo. That's why the point in the Important section.

Maybe we can create a "Prerequisites" section of the README that tells 1. Which version of Docker to run, 2. That it assumes Docker to be runnable as standard users.

What do you think @kdaud ?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What do you think @kdaud ?

For normal users on Linux os the last installation step requires to prepend sudo or sudo -E to have a successful run otherwise it throws exceptions of this kind and other permission related logs.

Maybe we can create a "Prerequisites" section of the README that tells 1. Which version of Docker to run, 2. That it assumes Docker to be runnable as standard users.

After testing out different versions of docker, I noticed all docker versions >20.10.12 run well including the latest SNAPSHOT so I would think we should not restrict a particular version for users, may be we can recommend the minimum version to be used.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For normal users on Linux os the last installation step requires to prepend sudo or sudo -E to have a successful run otherwise it throws exceptions of this kind and other permission related logs.

I don't think that's necessary true.

  1. "Normal users" on Linux OS should have followed the complete installation options, which includes adding the current user to a docker group and with sudo access.

  2. The first link you paste I think is actually due to an incorrect Docker Compose version. In older versions of Docker Compose, the expected format of the values of some of the keys have changed format (single value VS array for instance)

  3. The second link you've shard is actually because running Maven as sudo (root). Don't know why this person was runnning Maven as sudo...

After testing out different versions of docker, I noticed all docker versions >20.10.12 run well including the latest SNAPSHOT so I would think we should not restrict a particular version for users, may be we can recommend the minimum version to be used.

OK fair enough. I actually had rather in mind to advise the version of Docker Compose, not Docker itself.
That's because of the issue explained above. Plus, in older version you would run docker-compose. In newer version, docker compose

```
</td>
</tr>
</table>

<p align="center">
<img src="./readme/docker-compose-up-shadow.png" alt="docker-compose up" height="200">
</p>

**Important:** This assumes that you run the `docker` command as the same user and in the same window in which you exported your variables.
If Docker is run as `sudo`, the variables won't have an effect. Make sure to either export them as root, or run `docker` with `sudo -E` option to preserve the user environment. See [Docker on Linux Post-install steps](https://docs.docker.com/engine/install/linux-postinstall/)
**Important:** This assumes that you run the `docker` command as the same user and in the same window in which you exported your variables. On Linux we advise to run `docker` with `sudo -E` option to preserve the user environment as `su`. See [Docker on Linux Post-install steps](https://docs.docker.com/engine/install/linux-postinstall/)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

environment as su

That piece I'm not sure to understand


### Access the servers:

Expand Down