Skip to content

Setup Docassemble Document Automation Locally

With assembling your documents, Microsoft Word only goes so far. We continue our docassemble journey by setting up docassemble to run without a remote server.

Dele Omotosho
Dele Omotosho
7 min read

Table of Contents

In this guide, we will setup our system to run docassemble without using the playground or a server.

This allows us to use a regular text editor, save our work so we can collaborate on interviews with colleagues and we get an easier way to use MS docx templates with docassemble.

💡
This article is part of the series on using document automation with docassemble.

At the end of this guide, you will be able to design an interview this way:

Running docassemble locally
💡
if you're not comfortable with docassemble yet, use it from the playground

Requirements to install docassemble on your system

First, confirm your system has these minimum requirements:

If you're good with this, let’s get into the steps.

Install docker for docassemble

Docker is like a computer within your computer. It allows you to run an application that you won't otherwise be able to install and run on your computer.

Let's install it:

Go to docker's website and download the proper version for your operating system. Through the rest of this guide, I will use Windows.

When the download is complete, we'll run the installation file. I'm starting from this point:

Download docker to desktop

As I open it, I get this notification:

Allow device modification

Continue the rest of the install. Accept all the default options.

With docker installed, we install the software that allows us to track changes to our files, Git and GitHub.

Install Github and Git to allow docassemble Source Control

Go to https://desktop.github.com/ to download GitHub Desktop.

Download and install GitHub desktop

While installing this is all you see:

GitHub in the installation process

Hang in there, it's installed in the background.

When it's complete, you get this screen:

GitHub installation complete

At this point, you have 2 options:

If you don't have a GitHub account , click Create your free account or do it here, then continue to the next step.

💡
GitHub is the website that allows you to collaborate with others. Think of GitHub like a group email inbox for documents, but unlike email, GitHub allows us to track all the changes on those documents.

With your new (or exciting) GitHub account, click the Sign in to GitHub.com.

Sign in to GitHub from the Desktop App

When that's complete, it brings us back to this:

Confirm Git Details

Confirm the details are correct and click Finish.

With this done, we're ready to start automating our documents with Docassemble.

Write a sample docassemble interview from your system

To confirm all works, we will try a sample document assemble project.

Open your GitHub desktop. Click Clone a repository from the Internet... select URL, in the text box enter: deletosh/docassemble-premier then click Clone.

Create a copy of the project on your computer

Finally, to see what all the files look like, hit Repository > Open in Visual Studio

Open project in VS Code

With our VS Code open, confirm we can run an interview on our computer. Click through docassemble > template > questions then open sample.yml

Open interview yml file

To make working with coding docassemble easier, we want to add additional customization to VS Code.

We will be type several commands in the terminal (sometimes called, command line, or cmd.exe). It's that app on Windows that looks like this:

what does cmd.exe look like

We want this to work better and make it easier to use inside VS code.

Go to https://mridgers.github.io/clink and EXE (installer)

Download Clink for Windows

Once you downloaded this, open and install the file. Keep all the default options.

Take note of where we installed the app. Mine is at C:\Program Files (x86)\clink.

Install clink

Browsing through folders

Before we continue, let me expand on what "C:\Program Files (x86)\clink" means.

When you install any app on your computer, it saves it somewhere on your computer, in our case, that somewhere is "C:\Program Files (x86)\clink." The first folder is "C:" (your main computer drive). Inside that we have the next folder "Program Files (x86)"; inside it we have "clink."

To navigate to our final folder (clink), you open Windows Explorer, open C:, then Program Files (x86), then click — the short way we represent the path to the final directory is "C:\Program Files (x86)\clink."

Let's move on.

With the install complete, go into the folder you installed click. Mine is C:\Program Files (x86)\clink, go into the version folder 0.4.9. Here's how I get to my folder,

Open Clink folder

Let's open VS Code. Click File  > Preferences > Settings.

Click on the settings icon

Open settings

Add the text below within the "{ }" section

"terminal.integrated.shell.windows": "C:\\Windows\\System32\\cmd.exe",
"terminal.integrated.shellArgs.windows": ["/K", "C:\\Program Files (x86)\\clink\\0.4.9\\clink_x64.exe"," inject"]
Add the settings to configure the terminal

(Note that the path in terminal.integrated.shellArgs.windows
In the Search settings box, enter terminal and in the Terminal: Explorer Kind select integrated

To confirm this is working as expected, open the terminal. Click Terminal > ‌New Terminal

Open a new terminal

We should see Clink v0.4.9.

Install Python and docassemble command-line app

Next, we will install python.

Python is a programming language, and that's docassemble's parent language. To make docassemble work properly offline, we need to install on our system.

Go to https://www.python.org/downloads/windows/, Click the most recent version and download.

Download the proper python version

Open the downloaded file. Before starting the installation, check the box Add Python 3.x to PATH, click Install Now

Start the installation

When your installation is complete, open VS Code and a new terminal then type python, it should look like this:

Check python works in your integrated terminal

If you see a message like the above, we're good.

We're now ready for the final step.

Install docassemble command-line tool (docassemblecli)

With python installed, let's install the tool that let's run docassemble locally.

Open VS Code, click Terminal > ‌New Terminal in the terminal enter pip install docassemblecli

Install docassemblecli tool

Let's run everything together

In the terminal, type docker-compose up -d . This is the command that starts a virtual computer.

Run docker composer

Open your browser and go to http://localhost. You might see this

Docassemble starting

After a few minutes, you should see Docassemble running. Sign in with the default password:

(the first time you login, it will have you change your password)

Run your first offline docassemble

Our main setup is now complete. Let's test our first interview.

First, go to Docassemble running on your system. In your browser, type http://localhost, in the navigation section, click My Profile.

Go to profile

On the next page, go to the Other settings > API keys

Go to API keys

Click ‌Add a New API Key and give it any name. Then click Create.

Finally, copy the resulting key

Create API key

Now, go back into VS Code with the project you previously created open.

Type code ~/.docassemblecli, this opens a new tab in VS Code.

In this section:

VS Code

Paste the API code you created in the previous section in the apikey. Save the file or Ctrl + S

Add API key

Next, let's rename the docassemble > template file to docassemble-premier

Rename to the docassemble project

Let's now open the sample.yml file

Next, type dainstall --norestart --playground ../docassemble-premier

Install the package

You should see Installed.

You can now go back to the browser at http://localhost, then go to the ‌Playground

Let's run the code.

Run interview

You're now good at developing Docassemble interviews from your system.

How to continue docassemble from locally

As you run your project, here are some things you need to keep in mind:

  • Every docassemble project is self-contained and you need to shut down docker and re-start docker in that project.
  • When you start a new project, you need to add and re-create your API keys. You cannot use the API key you've added before.

Docassemble allows you to automate your document assemble process, and it's a free alternative to the expensive hotdocs. This setup makes it flexible for you to write your interview and collaborate with other colleagues.

Let me know if you have questions in the comments.

docassembleDocument Automation

Dele Omotosho Twitter

I help improve your law practice with automated processes, legal tech and knowledge management.


Related Articles

Connect VS Code to GitHub for Legal Coding

If you're a legal professional and want to automate your document assembling process at the unbeatable price of FREE, you're in the right place. Tools like theformtool, HotDocs, Pythagoras, etc have comparable feature, the cost adds up. And for docassemble there's a catch: The learning curve is steep. That's where