Running Locally

You can run Cloud Document Maker locally on your machine if you’re using Linux. If you have a Windows-based machine then you can use Windows Subsystem for Linux. Ubuntu is the recommended operating system.

Environment Setup

Please see the steps below to configure the environment correctly.

Install Windows Subsystem for Linux following the steps via the provided link
Install Visual Studio Code
Install the Remote - WSL Extension
Start your Ubuntu OS on your Windows machine by searching for Ubuntu using the Windows key and then create a Linux user when prompted
Create a folder named “python-projects”
Terminal window
```
mkdir python-projects
```
Clone the Git repository to that directory. You can use GitHub Desktop via your Windows machine to to make things easier, simply use the \\wsl$\Ubuntu\home\\{your username}\python-projects path as the directory
Grant read and write access to all directories in your folder
Terminal window
```
chmod -R 0777 ./python-projects
```
Return to your Ubuntu terminal and navigate into the new directory
Terminal window
```
cd ./python-projects/python-document-maker
```
Start Visual Studio Code linked to your Ubuntu environment
Terminal window
```
code .
```
Install your extensions on your Visual Studio Code instance, as the Ubuntu version can have different extensions to your Windows version. Importantly, install the Python extension
Open the python-document-maker.code-workspace file via Visual Studio.
Run the Python setup script to make sure Python is setup correctly on your local environment. You may have to mark the file as executable first.
Terminal window
```
chmod +x ./python_setup.sh
```
Then run
Terminal window
```
./python_setup.sh
```
Run the Node.js setup script to make sure Node.js is setup correctly on your local environment. You may have to mark the file as executable first.
Terminal window
```
chmod +x ./nodejs_setup.sh
```
Then run
Terminal window
```
./nodejs_setup.sh
```
Run the install script via the terminal to create the Virtual Environment and install the dependencies. This also installs the dependencies for the documentation site. You may have to mark the file as executable first.
Terminal window
```
chmod +x ./install.sh
```
Then run
Terminal window
```
./install.sh
```

Running

Start the Virtual Environment via the terminal.

source .venv3.8/bin/activate

You can now start the application.

python application.py

Alternatively, run the file in Visual Studio Code. This will start Flask on your machine and a web server will be created.

You can now POST data to your local instance and produce templates on your own machine.

When working on a new version of Cloud Document Maker, make sure to update the version number in src/version.py.

Celery

Celery is the task queue used to queue “long-running” processes which can continue while the rest of the application runs as normal. For example, the webhookUrl setting uses Celery to provide a response to the client while Celery does the work of creating the document in the background and sending the file to the endpoint once it’s completed.

You can find more information on Celery here.

Cloud Document Maker uses Amazon SQS as a broker for Celery.

Cloud Document Maker uses SQL Server in RDS as a backend for storing task state.

Start the Celery worker via the terminal.

celery -A application:celery worker --loglevel=INFO

If you need to kill and restart the Celery worker on your machine, you can run this command in the terminal.

pkill -f "celery worker"

You then need to re-run the start command.

Documentation

To run a local version of the documentation site, change to the docs directory then run the dev script to start the docs site in development

cd docs
pnpm run dev