Setting Up - Digital-Law-Lab/Digital-Law-Lab GitHub Wiki

Install stuff

Install Visual Studio Code
Install Git
Reboot your machine

When your machine restarts...

Open a PowerShell window (Windows-X I), or type 'Powershell' at the start menu
Type code
- Visual Studio Code should start up
- Close and exit VS Code
Back at the PowerShell prompt type git
- you should get a screen full of git help messages

If these don't happen then contact @mferrare.

Accounts and Access

Accounts

Firstly, we're Google-centric 👎 but that's how it is. We get more free stuff through Google (such as Drive and API to authenticate) than with other providers (eg: Microsoft). So, you should use a gmail email address when asked to do so (eg: for GitHub and Docassemble etc)

GitHub

Create an account on GitHub. If you already have one, you can use that if you like (notwithstanding my comment on Google accounts above)

Docassemble

Click on the 'Sign in with Google' button. This will create a new Docassemble account for you with you gmail address.
- Do this on both the development and production servers.
Ask @mferrare to add you to the Digital Law Lab developers team.

You should be good to go!

Google Drive

Send your gmail address to @mferrare so you can get access to the Digital Law Lab Google Drive

Slack

Ask @mferrare to be invited to the Digital Law Lab Slack

Docassemble API Key

You need to create an API key so you can send code from VS Code to Docassemble. Once your account is created do the following:

From the top-right menu in Docassemble select 'Profile'

From the 'Other Settings' menu select 'API Keys'

Click on 'Add a New API Key'
Give your new key a name (it can be anything but don't forget it!) and set the key to have no authentication

Click 'Create'
Copy the key. You're going to need it! You might want to paste the key somewhere so you don't lose it. You'll need it for your secrets file.

Create a secrets.json file.

You need to store your API key so other scripts can access it. We'll store it in a file called secrets.json in your Software directory.

> cd $home\Software
> code secrets.json

Paste this into your new secrets.json file and then save it

{
  "dll_api_key" : {
    "api_key"  : "YourAPIKeyGoesHere",
    "api_root" : "https://llaw3301.achelp.net/api"
  }
}

Make sure you get the spacing, commas, colons and quotes correct otherwise we won't be able to process your secret properly.
You can call your secret anything you like. I've used dll_api_key in this document as an example. You can use that name too if you like!

Configure Stuff

GitHub

GitHub needs to know who you are. It needs the email you signed up to GitHub with and your full name. Use the following two commands (I've used my name as an example)

git config --global user.name Mark Ferraretto
git config --global user.email [email protected]

Python

We need to install the requests module into Python. Do this at the PowerShell command prompt

> py -m pip install requests

PowerShell

We suggest you create a directory where you will store all your repositories. eg: create a directory called Software in your home directory. You can do this from the PowerShell command line:

> cd $home
> mkdir Software

Clone the Digital Age repo

Now it's time to clone your first repo. You should start with cloning Digital Law Lab. That's where we keep the tools for the Code Lifcycle

Click on this Digital Law Lab link
Click on and then click on the copy icon to copy the URL to the repo:
Now clone the repo into your new Software directory

(hint: you can type git clone and then press Ctrl-V to paste in the URL you just copied above)
```
cd $home\Software
git clone https://github.com/Digital-Law-Lab/Digital-Law-Lab
```

Clone a Docassemble repo

All Docassemble repos start with docassemble-. Find one of those and clone it to your Software directory using the instructions above.

Set up a Docassemble Project

In your Docassemble Playground, create a 'Project' for the repo you just cloned. You need one project for every repo you clone.
A good idea is to match your Playground Project name with your cloned repo. So, if your docassemble repo is called docassemble-PackageName, then you should call your Playground Project 'PackageName'.

Select 'Manage Projects' from here:
Select 'Add a new project'
Type in the name
Click on 'Save'

Now you have your first Project read to go!

Setting up PowerShell for pushing code to Projects

We're all coding on Windows 10. We use PowerShell to help out with pushing code back and forwards.

Execution Policy

First, you need to allow the execution of PowerShell commands (which is not enabled by default). You do this by setting the Execution Policy. Type this at a PowerShell prompt

Set-ExecutionPolicy -ExecutionPolicy RermoteSigned -Scope CurrentUser

You only need to do this once.

Add an alias to your profile

Next, you need to edit your PowerShell profile and add some function()s to help you with pushing your code to Docassemble. You'll need to add a function for every Docassemble repo you clone (There are smarter ways to do this but I'm too lazy to figure them out!)

Edit your PowerShell Profile

> code $profile

Add this code:

$Software = "$home\Software"         # Assumes you created your Software directory in your home directory
$Secrets  = "$Software\secrets.json" # We assume you keep your API key in secrets.json in your Software directory
$MySecret = "dll_api_key"            # Change this to be whatever you called your API key when you set up your secrets.json
$DLL = "$Software\Digtal-Law-Lab" 
$PlaygroundManager = "$DLL\docassemble_playground_manager.py"

function pushPackageName {
  # This function will push the code in the docassemble-PackageName repo into the 
  # PackageName project in Docassemble.  We'll run this each time we want to run and/or
  # test the code.
  #
  # We need to create one of these functions for each docassemble package we work on. It's
  # a bit cumbersome but it's easy to understand.  When you copy this function for a new package
  # you will need to change:
  # - the name of the function (above)
  # - the value for $DAPackage (below)

  $DAPackage = "PackageName"
  $Repo = "$Software\docassemble-$DAPackage"
  py.exe $PlaygroundManager --secrets_file $Secrets --secret $MySecret --push --project $DAPackage --package $Repo
}

Save and exit.

Now, you need to reload your profile. Do this from the command line:

> . $profile

(yes, a full-stop, a space and then $profile. That's how you reload your profile)