The easiest way to deploy docassemble to install it using Docker. If you want very fine-grained control, you can install it without using Docker, but very few people do that.
Most people run docassemble on a virtual machine in the cloud. Since docassemble is free software, there are no fees for using it, but hosting a server on the internet will cost money (between $10 and $40 per month, or more, depending on what your performance, availability, and support needs are).
It is possible to run Docker on a laptop using Docker Desktop if you just want to quickly test it out, but running docassemble on a laptop is not a good long-term deployment platform because a laptop sleeps, hibernates, and shuts down frequently, and your Docker container might experience corruption as a result.
For high performance, you can run docassemble using a cluster of machines. However, for the vast majority of deployments, a single machine works fine.
Example of a deployment
Here is an example of one way to get a docassemble server up and running on the internet:
- Create an account at Amazon Lightsail.
- In Amazon Lightsail, create an “instance.” Select the “Unix/Linux” platform. Select the “OS only” blueprint “Amazon Linux 2.” Choose an “instance plan” that has 4 GB of memory and an 80 GB SSD.
- Go into the configuration of your instance and go to “networking.” Under “IPv4 Firewall,” you will see that the SSH port, port 22, and the HTTP port, port 80, are open. This is good; you will need these two ports. You will also need the HTTPS port, port 443, to be open, so click “Add rule,” select “HTTPS” as the “application,” and click “Create.”
- Note the “Public IP” of your “instance.” This is the IP address that computers on the internet will use to connect to your docassemble server.
- Create an account with Namecheap or another domain name
registrar. Purchase a domain name. For example, your domain name
foobar.com. Then, go into the DNS configuration and create an A record that maps the hostname
da.foobar.comto the IP address you found in the previous step. This means that your docassemble server will be available at
https://da.foobar.com. If you want, you can set up your DNS so that
https://foobar.comgoes right to your docassemble server.
- Many domain name registrars will offer you additional services besides DNS. You don’t need any of those things to use docassemble; you just need control over DNS for a domain.
- Go to the “Connect” tab and look at the information under “Use your own SSH client.” If you aren’t familiar with using SSH clients, now is a good time to learn. If you are a PC user, use PuTTY, and if you are a Mac user, use Terminal. For security reasons, you need to use a “key” to connect to your virtual machine. This provides greater security than a username and password. You should get familiar with how to use keys. It is possible to connect via SSH inside the web browser if you are impatient, but you should still take the time to learn how to use an SSH client on your computer.
- When you are connected to your machine using SSH, you can start running commands to install Docker. There are additional instructions in the Docker section of the documentation. On a Lightsail Amazon Linux machine, the commands to run are:
- Running “exit” will disconnect you from SSH. In order for the
usermodcommand to take effect, you need to log out and log in again.
- Reconnect via SSH and then create a text file called
- Set the contents of the file the following, substituting your own
hostname in place of
da.foobar.com, and substituting your own time zone in place of
America/New_York, and your own e-mail address in place of
- When you are done, press Ctrl-s to save the file and Ctrl-x to exit
- Now you can create a docassemble Docker container:
- Wait five minutes and then visit your docassemble server using
your web browser (e.g.,
- If it doesn’t work, check out the Troubleshooting section.
- Click the link in the corner to log in. Log in using “[email protected]” as the email and “password” as the password.
- You will then be asked to change the password.
Note that there are many different cloud providers and domain name registrars; Amazon Lightsail and Namecheap are mentioned here only as examples, not as recommendations.
This is one possible method of deployment. If your goal is to embed a docassemble interview on a different web site, you may wish to use a different deployment strategy using a web server and a reverse proxy.
After following the deployment steps above, you should have a working server. If you plan on using the server in the long term, it is recommended you take additional steps:
- Go to the User List from the menu. You will see there is one user on the
system, which is the administrator. The default adddress
[email protected]is obviously not a real e-mail address, so click Edit and change the e-mail address to your e-mail address.
- Set up e-mail sending and verify that it works.
- If the server is public-facing, set
- Consider setting
allow forgot passwordto
Falseif you plan to let users log in and you do not set
Truein your interviews.
- Go to the Configuration and customize the following settings:
If you are interested in hiring someone to develop an interview for you, you can propose a project in the #questions channel of the Slack group. Consultants who are available for projects include: