Devcontainer skeleton with Stata and R setup

This is set up for standard Codespaces command line operation, and optimized for AEA data editorial activities.

WARNING: Building the image required for this to work takes about 30 minutes! We strongly advise that you use Prebuilds if you wish to use this repeatedly.

Provided software

• Github CLI
• R (see Dockerfile for version)
• Rstudio (not started by default)
• Stata (see Dockerfile for version)

Starting this Codespace environment

To start this in Codespaces, go to your personal Codespaces space, and search for this repository to start a codespace, or, alternatively, fork this repository into your Github organization and launch Codespaces from the green button menu.

It will use any environment variables that you have assigned to this repository. See Github documentation on encrypted secrets to learn how to add specific secrets. You can add them to your personal settings or to the organization hosting the Codespace (e.g., AEA secrets or LDI secrets).

Useful environment variables (secrets)

These can be in personal space or organizational space.

• P_FREDKEY API key to use the FRED API within Stata. See this example.
• STATA_LIC_BASE64 - base64 encoded version of the Stata license file. REQUIRED if using Stata. See this discussion.

Generating your STATA_LIC_BASE64 secret

It can be generated with from a command line easily, for instance, from a running instance of this Codespace:

• start this Codespace
• Upload your Stata license file (stata.lic). You can use the Stata license installed on your own PC or Mac.
• open up a terminal (Ctrl-\')
• Assuming that you put the Stata license file into the root of the Codespace, use this command:

cat stata.lic | base64

• Go to your Github Codespace Secrets, and create a new secret with the value printed to your screen in the previous step.

Or you can generate this on a bash terminal on your own computer with Github CLI: gh secret set STATA_LIC_BASE64 -b"$(cat stata.lic | base64)" -v all -o YOURORG (may also work from Codespaces).

Typical usage at LDI Replication Lab

A typical usage of this codespace (but currently not standard practice at the Office of the AEA Data Editor) looks like this:

• Initialize a manuscript specific Bitbucket repository (instructions) using the replication-template.
• Initiate a codespace from this repository
• From command-line,
  • clone the Bitbucket repository: aeagit NNNN
  • obtain the replication package: python3 tools/download_openicpsr_private.py MMMMM
  • assess the package, write preliminary report
  • make any necessary changes to the code (hopefully none)
  • run the code: stata-mp -b do main.do
  • assess the output
  • finalize report

All at once:

# AEAREP-NNNN number
NNNN=1234
# ICPSR project number
MMMMM=12345

then

aeagit $NNNN
python3 tools/download_openicpsr_private.py $MMMMM
cd $MMMMM
stata-mp -b do main.do

Unfortunately, it is rarely that easy...

AEA-specific variables

Personal space

You need to set these in your personal settings to effectively use this environment. Naming should indicate their purpose pretty well.

• P_BITBUCKET_USERNAME
• P_BITBUCKET_PAT
• P_DOCKERHUB_LOGIN
• P_DOCKERHUB_PAT

Organization space

• ICPSR_EMAIL
• ICPSR_PASS - ICPSR credentials for downloading from the unpublished replication packages. Note that ICPSR does not provide an API, so this is actually the password (not great security practice)

Rstudio

To enable Rstudio as the primary interface, see notes in the Dockerfile, edit within Codespaces, and rebuild.