Treadl

This is a monorepo containing the code for the web and mobile front-ends and web API for the Treadl platform.

Deploying your own version of Treadl

Run with Docker (recommended)

We publish and maintain a Docker image for Treadl, which is the easiest way to get started.

We recommend using Docker Compose and our template docker-compose.yml to configure the app and the MongoDB database. Download this file to your computer and then run docker compose up to start Treadl.

In production, it is very important to change the values in the file's environment block to suit your own setup. We also strongly recommend the use of a reverse-proxy to handle TLS connections to the app.

Alternative deployment

In scenarios where you want more control over the deployment, or you are more concerned with scalability, you may wish to use a more manual approach.

In this case you'll need to:

• Launch (or re-use) a MongoDB cluster/instance
• Provision a server or service for running the Flask app (in the api/ directory), ensuring all dependencies are installed and that it runs with the needed environment variables
• Build the web front-end (with npx vite build using your needed environment variables, having installed dependencies with npm install) and host the resulting dist/ directory on a server or object store.

S3-compatible object storage

Treadl uses S3-compatible object storage for storing user uploads. If you want to allow file uploads (apart from WIF files, which are processed directly), you should create and configure a bucket for Treadl to use.

Hosted options:

• Amazon S3
• Linode Object Storage
• DigitalOcean Spaces

Self-hosted options:

• MinIO

Once you have a bucket, generate some access keys for the bucket that will enable Treadl to read from and write to it. Ensure you make a record of the following for inclusion in your environment file/variables:

• Bucket name: The name of the S3-compatible bucket you created
• Endpoint URL: The endpoint for your bucket. This helps Treadl understand which provider you are using.
• Access key: The "username" or access key for your bucket
• Secret access key: The "password" or secret access key for the bucket

Note: assets in your bucket should be public. Treadl does not currently used signed requests to access uploaded files.

Running Treadl locally in development mode

To run Treadl locally, first ensure you have the needed software installed:

• Python ^3.12
• Node.js (we recommend v22.x)
• Docker (we use this for the Mongo database)
  • It can be installed via the Docker website or your package manager
  • Ensure the Docker service is running
• Taskfile (convenience tool for running tasks)
  • This can be installed using brew install go-task

To begin, clone this repository to your computer:

git clone https://git.wilw.dev/wilw/treadl.git

Next, initialise the project by installing dependencies and creating an environment file for the API:

task init

This generates a 'envfile' in your 'api' directory. You can edit this as needed (though the defaults should allow you to at least launch the app). Note: if you run this command again then any changes you made to your envfile will be overwritten.

Finally, you can start the API and web UI by running:

task

Note: this command also starts the MongoDB database on port 27017. If the DB is already running, you'll see errors reported, but the API and web will still be launched.

You can now navigate to http://localhost:8002 to start using the app.

If you pull updates from the repository in the future (e.g. with git pull) you may need to ensure your dependencies are up-to-date before starting the app again. This can be done with:

task install-deps

Contributions

Contributions to the core project are certainly welcomed. Please get in touch with the developer for an invitation to join this repository.