Document workflows

[maurolepore]

Building on work by Clare, this PR aims to document in README the two main workflows that the PACTA_analysis repo provides.

[maurolepore]

@cjyetman, if you have some time it would be great to have your opinion on this, my first try at documenting PACTA workflows in README. So far I only documented the so called "online" workflow; next I'll work on the "offline" workflow. (I propose to abandon the terms "online/offline workflow" in favor of "single-inputs/multiple-inputs workflow" or something else -- I explain why in README).

I recognize the most important workflow I have not documented yet. But I preferred to start with something more familiar to gain momentum.

https://github.com/2DegreesInvesting/PACTA_analysis/blob/generalize-workflow/README.md

[cjyetman]

I'm in favor of abandoning the "online"/"offline" terms, but I'm not in favor of abandoning having a term for the web tool scripts that clearly, unambiguously suggests that they are intended to work on the web server and must serve that purpose above all else. So I'm not sure "single-inputs" or "multiple-inputs" is adequate... in fact, it's not even clear to me which of those you would use to refer to the web tool scripts. My guess is "single-inputs" because it generally runs one portfolio at a time? But I would hope that the "offline" version would be capable of running a single portfolio, and I would prefer that if an analyst comes to this repo and says to themselves "I need to run PACTA on this single portfolio" that they're not then guided to use the web tools.

[AlexAxthelm]

Blocking: These lines seem better suited to go into a docker-compose.override.yml, rather than the core docker-compose file.

[AlexAxthelm]

Non-blocking: Do we know what CRAN's retention policy for old package binaries is?

[maurolepore]

Blocking: These lines seem better suited to go into a docker-compose.override.yml, rather than the core docker-compose file.

Thanks! I'm new to compose and first time I learn about *overide.yml. Is this suggestion to (1) protect the PASSWORD (and we would exclude *overide.yml from the repo), or (2) to make it easier to reuse the app for other purposes?

If (1) I understand we could then do:

docker-compose -f docker-compose.yml -f /path/to/secrets/outside/repo/docker-compose.overide.yaml up

This is pretty cool but makes the call to up cumbersome. Is docker secret is a better approach (maybe harder to configure but easier start the container with docker-compose up)?

[maurolepore]

BTW. I didn't anticipate that this PR would be about docker so I'll move the docker bits to a focused PR.

[AlexAxthelm]

Is docker secret is a better approach

In my experience, unless there's a real secret, I find it's easiest to just put configuration stuff in a .env file, and keep that out of the repo (via .gitignore)

[maurolepore]

I'm closing this PR because it's too big and unfocused. I'll follow up with smaller more focused ones.