Skip to content

Update commcare cloud setup instructions #6458

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

Merged
merged 9 commits into from
Jan 20, 2025
Merged

Update commcare cloud setup instructions #6458

Changes from 1 commit
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
4e48c2f
General minor changes to wording and ordering
gherceg Jan 3, 2025
26d8044
Don't suggest ansible password for vault file
gherceg Jan 3, 2025
3d9717c
Ensure load_config.sh is run before init-ansible
gherceg Jan 3, 2025
3a840ee
Remove outdated instruction
gherceg Jan 3, 2025
01c3af2
Modify initial steps to deploy HQ
gherceg Jan 3, 2025
9ce97bc
Ensure initial ssh config accepts interactive auth
gherceg Jan 3, 2025
47c96bb
Use su instead
gherceg Jan 3, 2025
17240b4
Revert "Ensure load_config.sh is run before init-ansible"
gherceg Jan 6, 2025
e347f5d
Fix "Coud" typo
gherceg Jan 6, 2025
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
111 changes: 54 additions & 57 deletions docs/source/installation/2-manual-install.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,7 @@ cluster’s proxy server.

Prepare all machines for automated deploy
-----------------------------------------
Do the following on the monolith, or on each machine in the cluster.
Do the following on the monolith or on each machine in the cluster.

Enable root login via SSH
~~~~~~~~~~~~~~~~~~~~~~~~~
Expand Down Expand Up @@ -126,46 +126,14 @@ To be used in the installation process.
$ sudo touch /var/log/ansible.log
$ sudo chmod 666 /var/log/ansible.log

Install system dependencies
~~~~~~~~~~~~~~~~~~~~~~~~~~~
This only needs to be done on the control machine. In the case of a monolith,
Prepare control machine for automated deploy
--------------------------------------------
The following steps only need to be done on the control machine. In the case of a monolith,
there is only one machine to manage so that is also the control machine. In
our example cluster, the control machine is named “control1”.


1. SSH into control1 as the “ansible” user, or the user you created during installation. You can skip this step if you are installing a monolith:

::

$ ssh ansible@control1

This instruction assumes that the control machine’s name resolves to its IP address.
Replace the name with the IP address if necessary.

2. On the control machine, or the monolith, install required packages:

::

$ sudo apt update
$ sudo apt install python3-pip python3-dev python3-distutils python3-venv libffi-dev sshpass net-tools

3. Check your default Python version for Python 3.x:

::

$ python --version

If your default version is not 3.x or if the “python” command was
not found, make python3 your default by running the command below,
otherwise skip it.

::

$ sudo update-alternatives --install /usr/bin/python python /usr/bin/python3 10


Copy link
Contributor

Choose a reason for hiding this comment

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

is this not needed anymore?

I used this one recently when trying to do a test install.

Copy link
Contributor

Choose a reason for hiding this comment

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

Oh I see, its moved.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Given that we specify ubuntu 22.04 at the moment, 3.10 will be the system version, so it seems fine to simplify the step to just run this rather than specify the condition.

Create a user for yourself
--------------------------
~~~~~~~~~~~~~~~~~~~~~~~~~~

In general, CommCare environments are managed by a team. Each member of
the team has their own user account.
Expand All @@ -180,22 +148,44 @@ add them to the “sudo” user group. For example, if your username were
...
$ sudo usermod -a -G sudo jbloggs

Switch to this user for the remainder of these setup steps:

::

$ sudo -iu jbloggs


Install system dependencies
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Install CommCare Cloud
----------------------
1. Install the required packages:

1. On the control machine or the monolith, install and configure Git:
::

$ sudo apt update
$ sudo apt install python3-pip python3-dev python3-distutils python3-venv libffi-dev sshpass net-tools git

2. Configure Git:

::

$ sudo apt install git
$ git config --global user.name "Jay Bloggs"
$ git config --global user.email "[email protected]"

(Of course, substitute “Jay Bloggs” with your name, and
“[email protected]” with your email address.)

2. Clone and initialize CommCare Cloud:
3. Make python3 default for python command:

::

$ sudo update-alternatives --install /usr/bin/python python /usr/bin/python3 10


Install and Configure CommCare Cloud
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1. Clone and initialize CommCare Cloud:

::

Expand All @@ -211,15 +201,23 @@ Install CommCare Cloud
Do you want to have the CommCare Cloud environment setup on login?
(y/n): y

3. Clone the sample CommCare Cloud “environments” folder into your home
If the input times out before entering 'y', you can follow the prompt instructions
to setup CommCare Coud on login:

::

$ echo '[ -t 1 ] && source ~/init-ansible' >> ~/.profile


2. Clone the sample CommCare Cloud “environments” folder into your home
directory.

::

$ cd ~
$ git clone https://github.com/dimagi/sample-environment.git environments

4. Rename your environment. You could name it after your organization
3. Rename your environment. You could name it after your organization
or your project. If you are installing a monolith you could leave
its name as “monolith”. For this example we will name it “cluster”.

Expand All @@ -229,36 +227,36 @@ Install CommCare Cloud
$ git mv monolith cluster
$ git commit -m "Renamed environment"

5. Remove the “origin” Git remote. (You will not be pushing your
4. Remove the “origin” Git remote. (You will not be pushing your
changes back to the Dimagi “sample-environment” repository.)

::

$ git remote remove origin

6. (Optional) You are encouraged to add a remote for your own Git
5. (Optional) You are encouraged to add a remote for your own Git
repository, so that you can share and track changes to your
environment’s configuration. For example:

::

$ git remote add origin [email protected]:your-organization/commcare-environment.git

7. Configure your CommCare environment.
6. Configure your CommCare environment.

See :ref:`configure-env` for more information.

8. Add your username to the ``present`` section of
7. Add your username to the ``present`` section of
``~/environments/_users/admins.yml``.

::

$ nano ~/environments/_users/admins.yml

9. Copy your **public** key to ``~/environments/_authorized_keys/``.
8. Copy your **public** key to ``~/environments/_authorized_keys/``.
The filename must correspond to your username.

10. Change “monolith.commcarehq.test” to your real domain name,
9. Change “monolith.commcarehq.test” to your real domain name,

::

Expand All @@ -281,8 +279,7 @@ Install CommCare Cloud
- ``ALLOWED_HOSTS``



11. Change default emails
10. Change default emails

::

Expand All @@ -291,7 +288,7 @@ Install CommCare Cloud
You should find references in ``public.yml``


12. Configure ``inventory.ini``
11. Configure ``inventory.ini``

.. rubric:: For a monolith
:name: for-a-monolith
Expand Down Expand Up @@ -429,7 +426,7 @@ Install CommCare Cloud
db1
db2

13. Configure the ``commcare-cloud`` command.
12. Configure the ``commcare-cloud`` command.

::

Expand Down Expand Up @@ -467,13 +464,13 @@ Install CommCare Cloud

$ cp ~/commcare-cloud/src/commcare_cloud/config.example.py ~/commcare-cloud/src/commcare_cloud/config.py

Update the known hosts file
Update the known hosts file (substituting your environment name if necessary)

::

$ commcare-cloud cluster update-local-known-hosts
Copy link
Contributor

Choose a reason for hiding this comment

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

I know we have used cluster as environment name in the entire doc but would it be clearer if we use which would indicate that this has to be replaced?

Suggested change
$ commcare-cloud cluster update-local-known-hosts
$ commcare-cloud <env> update-local-known-hosts

btw I am totally fine with the way it is right now it was just a thought that I wanted to share with you.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Yeah I do want to make this change. I also want to make a sweeping change to the $ syntax before each command as it makes copy/pasting annoying, so was planning to do this in a separate PR if that is ok with you.

Copy link
Contributor

Choose a reason for hiding this comment

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

Yeah. Totally fine by me.


14. Generate secured passwords for the vault
13. Generate secured passwords for the vault

In this step, we’ll generate passwords in the ``vault.yml`` file.
This file will store all the passwords used in this CommCare
Expand All @@ -494,7 +491,7 @@ Install CommCare Cloud
Find the value of “ansible_sudo_pass” and record it in your password
manager. We will need this to deploy CommCare HQ.

15. Encrypt the provided vault file, using that “ansible_sudo_pass”. (As
14. Encrypt the provided vault file, using that “ansible_sudo_pass”. (As
usual, substitute “cluster” with the name of your environment.)

::
Expand Down