---
title: "Troubleshoot Locally — Spiff Arena 0.1 documentation"
description: "When setting up the SpiffWorkflow backend project locally, you might encounter issues related to the sample-process-models directory. This documentation aims to address those concerns."
source_url: https://spiff.works/docs/spiff-arena/how_to_guides/troubleshoot_locally.html
---

☰ Menu

# Troubleshoot Locally[](#troubleshoot-locally "Link to this heading")

When setting up the SpiffWorkflow backend project locally, you might encounter issues related to the `sample-process-models` directory.
This documentation aims to address those concerns.

## Problem[](#problem "Link to this heading")

While following the instructions provided in the repository to set up the SpiffWorkflow backend project locally, you may find that the script `./bin/run_server_locally` expects the `sample-process-models` directory to be present.
However, this directory might not be immediately available in the repository.

## Solutions[](#solutions "Link to this heading")

### 1. Clone the `sample-process-models` Repository[](#clone-the-sample-process-models-repository "Link to this heading")

The `sample-process-models` directory refers to a separate repository.
To resolve the issue:

- Navigate to <https://github.com/sartography/sample-process-models>.
- Clone the repository right next to `spiff-arena`.
- Run the `./bin/run_server_locally` script.

### 2. Use Any Git Repository[](#use-any-git-repository "Link to this heading")

If you prefer not to use the `sample-process-models` directory or want to start from scratch:

- Locate or create a git repository.
- Run the following command with the path to your chosen repository:

  ```
  SPIFFWORKFLOW_BACKEND_BPMN_SPEC_ABSOLUTE_DIR=/path/to/any/git/repo ./bin/run_server_locally
  ```

### 3. Use Docker Compose[](#use-docker-compose "Link to this heading")

For a potentially faster setup:

- Follow the guide at <https://www.spiffworkflow.org/posts/articles/get_started_docker>.
- Use the provided commands to run the server with Docker Compose.

### 4. Mac Install Issues[](#mac-install-issues "Link to this heading")

First, follow the README.md at the root of the spiff-arena repo.
If you’re on a Mac and trying to run natively (this might also apply elsewhere) and get errors when running `poetry install`, many of these issues are related to relational database engine libraries.
Many people have encountered these problems, so hopefully, the solution to your specific issue is easy to find, but this is not always the case.
You may need to install additional system dependencies:

```
brew install mysql-client pkg-config
export PKG_CONFIG_PATH="$(brew --prefix)/opt/mysql-client/lib/pkgconfig"
pip install mysqlclient
pip install psycopg2
```

One person decided that mysqlclient and psycopg2 were more trouble than they were worth and removed them from the pyproject.toml, opting instead to run `poetry add pymysql`.
If you are using mysql, psycopg2 is not necessary, and pymysql is a pure Python implementation of the MySQL client library.
In that case, Python won’t recognize MySQLdb as a module, so after the above installs (which you would do pre-Poetry), add these lines to `__init__.py` in the backend project:

```
import pymysql
pymysql.install_as_MySQLdb()
```

### 5. Access Hosted Version of Spiff[](#access-hosted-version-of-spiff "Link to this heading")

If you prefer not to install anything locally:

- Navigate to <https://www.spiffworkflow.org/posts/articles/get_started>.
- Access a version of Spiff hosted on the internet.

Setting up the SpiffWorkflow backend project locally can be straightforward once you’re aware of the dependencies and options available.
Whether you choose to clone the `sample-process-models` repository, use a different git repository, or opt for Docker Compose, the solutions provided should help you get started without any hitches.

If you encounter further issues, always refer back to the repository’s README or seek assistance from our Discord community.