Skip to content

README.dev.md

Latest commit

 

History

History
191 lines (126 loc) · 7.85 KB

README.dev.md

File metadata and controls

191 lines (126 loc) · 7.85 KB

Developer documentation

If you're looking for user documentation, go here.

Firstly, a note on the development workflow with docassemble.

This repository is generated by docassemble. docassemble has its own integration with GitHub. The standard workflow when using docassemble would be to create a project in the docassemble playground on a running docassemble site. This project can be developed and tested in the docassemble playground and then saved to GitHub by docassemble itself. Finally, the saved project can be linked to the same docassemble site (outside the playground) and set as default interview, i.e. the site that visitors will see.

Unfortunately, this disables the major strengths of git/GitHub for development such as the descriptive commit history, shared development, and pull requests and reviews. This cannot be married with our ethics on fair software. Therefore, we use a slightly more convoluted development process that enables the desired git/GitHub features.

The main change is that we recommend local development directly on the repository. Any changes to the repository can be tested in the docassemble playground by linking and updating the particular development branch. Any changes merged into main can be deployed to the docassemble site by updating the linked repository in docassemble.

Development install

Based on https://docassemble.org/docs/docker.html

In case of Windows, please break glass: https://docs.docker.com/engine/installation/windows/ or OS Z: https://docs.docker.com/engine/installation/mac/

# Install docker.
sudo apt -y update
sudo apt -y install docker.io
# Test whether docker works.
docker run hello-world
# If not:
#reboot

Note that the docassemble documentation recommends creating a new group for docker to give it access rights. However, we recommend instead running docker with the sudo command to only supply rights on demand.

Provide root access to docker.

If you don't care about the security of your system and your prefer the convenience of not having to type your password, you could give docker root access.

! Be aware that there are ways to break out of a docker container that is publicly hosted.

sudo groupadd docker
sudo usermod -aG docker $USER
newgrp docker

Deploy docassemble

Based on https://docassemble.org/docs/docker.html#starting

sudo docker run -d -p 80:80 -p 443:443 --restart always --stop-timeout 600 jhpyle/docassemble

After a few minutes, docassemble should be running at http://localhost:80 (or "localhost/" for short).

When accessing the hosted site for the first time, log in using the default admin@admin.com account with its default "password". This prompts you to change the password to something less pre-breached.

We recommend you immediately add another admin user with a functioning email: account (top right) -> User List -> Menu -> Add a user.

Docker primer

# List all docker containers.
sudo docker ps -a

# Stop a docassemble container.
sudo docker stop -t 600 [containerid]

# Restart a docassemble container.
sudo docker start [containerid]

# Remove a stopped container.
sudo docker rm [containerid]

Note that the docassemble container is given 10 minutes to shut down gracefully before docker kills it. This enables the internally running docassemble PostgreSQL server to backup the docassemble data. Interupting this process may corrupt that data.

Development

Load this repository into your playground: account -> Playground -> Folders -> Packages -> Pull. Set the GitHub URL to the URL of this GitHub, or your fork, and choose the branch to develop. Install (bottom).

Test playground interview

Select the main interview yml file. account -> Playground. Change the file in focus (4th menu item) to software.yml. Save and Run (bottom).

The following is split into two different workflows. You can either deploy docassemble on a (cloud) server and develop remotely, or you can deploy docassemble on your own machine and develop locally. We recommend developing locally, because this enables git/GitHub features according to best practices. However, we also provide guidance to develop remotely for convenience.

Remote development

To develop remotely, GitHub is integrated with docassemble. This enables pushing changes you make in the playground directly to this repository.

Based on https://docassemble.org/docs/installation.html#github

Register docassemble in your GitHub account as an OAuth application: On GitHub, open your account -> Settings -> Developer Settings -> OAuth Apps -> New OAuth app. Applicatin name: SS-NES interview server Homepage URL: [docassemble URL] Authorization callback URL: [docassemble URL]/github_oauth_callback Register application Generate a new client secret

Note the Client ID and Client secret.

On your docassemble server, account -> Configuration oauth: github: enable: True oauth: github: id: [Client ID] oauth: github: secret: [Client secret] Save

After restarting the docassemble system, authorize the GitHub integration account -> Profile -> Other settings -> GitHub integration -> Configure -> Authorize [github name].

Once GitHub integration is set up, the playground package gains a button named GitHub. This will commit the changes you made in the Playground to this repository.

Note that while developing remotely, you can write a commit message, but you don't have any other control over what to commit.

Local development

If you have deployed docassemble locally, you can use the scripts pull_playground.sh and push_playground.sh to move files between this repository and the docassemble site.

pull_playground.sh pulls the interview files from a locally running docker container to this repository.

push_playground.sh pushes the interview files from this repository to a locally running docker container. Refresh the browser page and run the questionnaire from the playground.

Both scripts accept these optional input arguments:

  • -a [docassemble account number] (default: 1, which is usually admin@admin.com)
  • -c [container ID] (default: first running docker container)
  • -k (keep temporary directory; default: remove)
  • -t [temporary directory] (default: ./container)

Note that these scripts cannot match docassemble account numbers to specific accounts. If you are unsure which number your account has, you can call pull_playground.sh and browse the temporary directory. Each account stores its files in numbered subdirectories in this directory structure; the number is the account number.

While this process may become cumbersome when the docassemble site has a lot of accounts, this shouldn't become a problem if it is hosted locally.

Note that the temporary directory is only used because the docker container and repository use a different directory structure to organize the interview files. Any actual content of this directory is equivalent to the content in the repository.

Deploy interview

Deploying an interview to a docassemble site can be done regardless of whether you are developing locally or remotely.

On your docassemble server, account -> Package Management. Fill the remote URL of this repository in Github URL. It may take a little while to find the repository. Once detected, you can select the correct branch and press Enter. This adds this repository to the list of existing packages. After pushing any changes to the deployed branch, you should Update the package in this list.

Set the correct yml file as default interview: On your docassemble server, account -> Configuration. default interview: docassemble.SMPDecisionTree:software.yml Save

After restarting the docassemble system, the root URL should point to the SMP Decision Tree interview.

How to contribute

Suggestions/improvements/edits are most welcome. Please read the contribution guidelines before creating an issue or a pull request.