-
Notifications
You must be signed in to change notification settings - Fork 20
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Signed-off-by: Kipchirchir Sigei <arapgodsmack@gmail.com>
- Loading branch information
Showing
1 changed file
with
204 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,204 @@ | ||
| # OpenSRP Deployment | ||
|
|
||
| ### Setting up an opensrp web instance | ||
|
|
||
| We support 3 deployment environments: stage, preview and production so one should first decide under which environment they want to set up the site in. | ||
|
|
||
| You also need to have the necessary SSH keys set up in your machine in order to gain access to the deployment server. Kindly refer to [this](https://github.com/onaio/infrastructure/blob/35172d3e0986d4f55749a780122326340b40e35a/docs/tools/ansible_playbooks.md) doc on how to generate and sign the SSH keys. | ||
|
|
||
| ### Adding inventories for a new web instance | ||
|
|
||
| To add inventories for an existing client, first clone the opensrp inventories repo [here](https://github.com/onaio/opensrp-inventories), then navigate to the host/client folder of choice. Also remember to clone the [playbooks](https://github.com/opensrp/playbooks/) repo in the same location as the opensrp inventories and follow the setup instructions as described [here](https://github.com/opensrp/playbooks#setup). | ||
|
|
||
| Each host has a stage, preview and production folder. Change dir into the environment folder of choice then create a `vars.yml` file with a set of variables used by the 4 ansible roles listed below that are used when running the playbook command: | ||
|
|
||
| - certbot - Installs certbot that is used to create website SSL certificates | ||
| - react - A role used to install react apps | ||
| - express - A role that installs and configures an express app | ||
| - nginx - Installs and configures Nginx | ||
|
|
||
| i.e if the client is `wellness-pass` and we want to deploy a staging site, we create the vars.yml file under `wellness-pass/stage/group_vars/web` directory. | ||
|
|
||
| Ansible roles usually offer a level of abstraction useful for organizing playbooks. | ||
|
|
||
| Below is a list of vars to be added in the host `vars.yml` file to be used by the above roles: | ||
|
|
||
| ``` | ||
| # General | ||
| ansible_ssh_user: "ubuntu" | ||
| ansible_ssh_host: <insert site url> | ||
| # keycloak | ||
| keycloak_url: <insert keycloak url> | ||
| keycloak_realm: <insert keycloak realm> | ||
| # OpenSRP | ||
| opensrp_server_url: <insert opensrp server base url> | ||
| opensrp_client_id: <insert oauth client id> | ||
| # Web application | ||
| app_env: <insert environment i.e preview> | ||
| app_title: <add app title> | ||
| # react | ||
| web_react_transpile_packages: true | ||
| web_react_remote_js_build: false # true when using admin host | ||
| web_react_system_user: "web" | ||
| web_react_system_user_home: "/home/{{ web_react_system_user }}" | ||
| web_react_codebase_path: "{{ web_react_system_user_home }}/react" | ||
| web_react_public_dir: "{{ web_react_codebase_path }}/app/build" | ||
| web_react_local_app_path: "{{ react_local_checkout_path }}/app" | ||
| web_react_git_url: "https://github.com/opensrp/web.git" | ||
| web_react_git_version: "v1.1.0" // update to use latest tag | ||
| web_express_system_user: "{{ web_react_system_user }}" | ||
| web_express_system_user_home: "/home/{{ web_react_system_user_home }}" | ||
| web_react_app_settings: | ||
| SKIP_PREFLIGHT_CHECK: "true" | ||
| REACT_APP_ENV: "{{ app_env }}" | ||
| REACT_APP_DOMAIN_NAME: "https://{{ deployed_site_name }}" | ||
| REACT_APP_WEBSITE_NAME: "{{ app_title }}" | ||
| // other env vars | ||
| # express | ||
| web_express_git_url: "https://github.com/onaio/express-server.git" | ||
| web_express_git_version: "v1.1.0" // use latest tag | ||
| web_express_git_key: | ||
| web_express_app_name: "{{ web_express_system_user }}" | ||
| web_express_codebase_path: "{{ web_express_system_user_home }}/express" | ||
| web_express_app_path: "{{ express_checkout_path }}" | ||
| web_express_log_path: "/var/log/{{ express_app_name }}" | ||
| web_pm2_express_service_name: opensrp_stage_web | ||
| web_express_app_settings: | ||
| NODE_ENV: "{{ app_env }}" | ||
| EXPRESS_OPENSRP_ACCESS_TOKEN_URL: "{{ keycloak_url }}/auth/realms/{{ keycloak_realm }}/protocol/openid-connect/token" | ||
| EXPRESS_OPENSRP_AUTHORIZATION_URL: "{{ keycloak_url }}/auth/realms/{{ keycloak_realm }}/protocol/openid-connect/auth" | ||
| EXPRESS_OPENSRP_USER_URL: "{{ opensrp_server_url }}/opensrp/user-details" | ||
| EXPRESS_OPENSRP_OAUTH_STATE: "opensrp" | ||
| EXPRESS_OPENSRP_CALLBACK_URL: "https://{{ deployed_site_name }}/oauth/callback/OpenSRP/" | ||
| EXPRESS_OAUTH_GET_STATE_URL: "https://{{ deployed_site_name }}/oauth/state" | ||
| EXPRESS_PORT: "3000" | ||
| EXPRESS_SESSION_NAME: <insert randon session name> | ||
| EXPRESS_SESSION_SECRET: "{{ vault_express_session_secret }}" | ||
| EXPRESS_SESSION_PATH: "/" | ||
| EXPRESS_REACT_BUILD_PATH: "{{ web_react_public_dir }}" | ||
| EXPRESS_SESSION_FILESTORE_PATH: "/tmp/express-sessions" | ||
| EXPRESS_PRELOADED_STATE_FILE: "/tmp/opensrp-web-state.json" | ||
| EXPRESS_SESSION_LOGIN_URL: "/login" | ||
| EXPRESS_FRONTEND_OPENSRP_CALLBACK_URL: "https://{{ deployed_site_name }}/fe/oauth/callback/opensrp" | ||
| EXPRESS_OPENSRP_CLIENT_ID: "{{ opensrp_client_id }}" | ||
| EXPRESS_OPENSRP_CLIENT_SECRET: "{{ vault_express_opensrp_client_secret }}" | ||
| EXPRESS_FRONTEND_LOGIN_URL: "/fe/login" | ||
| # certbot | ||
| web_use_certbot: true // set to false if you dont intend to install SSL cert on site | ||
| web_certbot_create_certs: true | ||
| web_certbot_renew_certs: true | ||
| web_certbot_install_cert: false | ||
| web_certbot_package: "python3-certbot-nginx" | ||
| web_certbot_version: "0.40.*" | ||
| web_certbot_site_names: | ||
| - "{{ deployed_site_name }}" | ||
| web_certbot_mail_address: "techops+{{ deployed_site_name }}@ona.io" | ||
| # nginx | ||
| nginx_install_only: true | ||
| nginx_version: "1.18.*" | ||
| web_nginx_site_names: | ||
| - "{{ deployed_site_name }}" | ||
| web_nginx_site_name: "{{ web_nginx_site_names[0] }}" | ||
| web_nginx_http_site_name: "{{ deployed_site_name }}-http" | ||
| web_nginx_https_site_name: "{{ deployed_site_name }}-https" | ||
| web_nginx_log_path: "/var/log/nginx/" | ||
| web_nginx_large_client_header_buffers: "4 8k" | ||
| web_nginx_access_logs: | ||
| - name: "timed_combined" | ||
| format: '''$http_x_forwarded_for - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" $request_time $upstream_response_time $gzip_ratio $request_length''' | ||
| options: null | ||
| filename: "access.log" | ||
| web_nginx_enabled_sites: | ||
| - "{{ web_nginx_http_site_name }}" | ||
| - "{{ web_nginx_https_site_name }}" | ||
| web_nginx_ssl_dir: /etc/nginx/ssl/{{ deployed_site_name }} | ||
| web_nginx_sites: | ||
| - server: | ||
| name: "{{ web_nginx_http_site_name }}" | ||
| listen: | ||
| - "80" | ||
| - "[::]:80" | ||
| server_name: "{{ web_nginx_site_names|join(' ') }}" | ||
| access_log: "{{ web_nginx_log_dir }}/{{ deployed_site_name }}-access.log timed_combined" | ||
| error_log: "{{ web_nginx_log_dir }}/{{ deployed_site_name }}-error.log" | ||
| rewrite: "^(.*) https://{{ web_nginx_site_name }}$1 permanent" | ||
| ssl: | ||
| enabled: false | ||
| - server: | ||
| name: "{{ web_nginx_https_site_name }}" | ||
| listen: | ||
| - "443 ssl" | ||
| - "[::]:443 ssl" | ||
| server_name: "{{ web_nginx_site_names|join(' ') }}" | ||
| access_log: "{{ web_nginx_log_dir }}/{{ deployed_site_name }}-ssl-access.log timed_combined" | ||
| error_log: "{{ web_nginx_log_dir }}/{{ deployed_site_name }}-ssl-error.log" | ||
| ssl: | ||
| add_ssl_directive: false | ||
| access_log_format: "timed_combined" | ||
| enabled: true | ||
| remote_src: true | ||
| create_symlink: true | ||
| cert: "fullchain.pem" | ||
| key: "privkey.pem" | ||
| src_dir: "/etc/letsencrypt/live/{{ deployed_site_name }}" | ||
| conf: "{{ deployed_site_name }}.conf" | ||
| # do not cache the service worker | ||
| location1: | ||
| name: "/service-worker.js" | ||
| add_header: 'Cache-Control "no-cache"' | ||
| proxy_cache_bypass: "$http_pragma" | ||
| proxy_cache_revalidate: "on" | ||
| expires: "off" | ||
| access_log: "off" | ||
| web_nginx_monit_protection: false | ||
| web_nginx_log_dir: "/var/log/nginx" | ||
| web_ginx_large_client_header_buffers: "4 8k" | ||
| web_nginx_first_start: true | ||
| ``` | ||
|
|
||
| You can also set up a `vault.yml` file where you can set sensitive values such as oauth secrets. To edit this file you should run the following command: | ||
| ` ansible-vault edit <client folder>/<environment>/group_vars/web/vault.yml --vault-password-file ~/opensrp/.vault_pass.txt` where the vault_pass file is a file with a password used to decrypt the vault.yml file. | ||
|
|
||
| After setting up the inventory we then add the client host or tag name under the `web` group var in the `hosts` file located at the root of each environment folder | ||
|
|
||
| ``` | ||
| [web:children] | ||
| <insert tag or client host name> | ||
| ``` | ||
|
|
||
| ### Deploying to stage | ||
|
|
||
| ``` | ||
| ansible-playbook -i opensrp-inventories/<client folder name>/staging/ web.yml --vault-password-file=~/opensrp/.vault_pass.txt -e react_git_version="v1.1.0" | ||
| ``` | ||
|
|
||
| ### Deploying to preview | ||
|
|
||
| ``` | ||
| ansible-playbook -i opensrp-inventories/<client folder name>/preview/ web.yml --vault-password-file=~/opensrp/.vault_pass.txt -e react_git_version="v1.1.0" | ||
| ``` | ||
|
|
||
| ### Deploying to production | ||
|
|
||
| ``` | ||
| ansible-playbook -i opensrp-inventories/<client folder name>/production/ web.yml --vault-password-file=~/opensrp/.vault_pass.txt -e react_git_version="v1.1.0" | ||
| ``` | ||
|
|
||
| If you have passed a default branch name to the `react_git_version` variable in the inventory of a particular host/client, you can deploy without having to provide the branch in the deploy command e.g | ||
|
|
||
| ``` | ||
| ansible-playbook -i opensrp-inventories/<client folder name>/production/ web.yml --vault-password-file=~/opensrp/.vault_pass.txt | ||
| ``` |