Local development


The steps below will get you up and running with a local development environment. All of these commands assume you are in the root of your generated project.

If you're new to Docker, please be aware that some resources are cached system-wide and might reappear if you generate a project multiple times with the same name.

Prerequisites

Docker & Docker Compose

If you don't have it yet, follow the installation instructions .

For development without docker see this page.

Vanty CLI

The project ships with a CLI tool to help you manage the local development workflow. Install it using pipx or poetry.

text
pipx install vanty

Build the Stack

This can take a while, especially the first time you run this particular command on your development system:

text
$ vanty dev init

# the command above is just a shortcut for
$ docker-compose build
$ pnpm run build
  • This will start up the docker-compose stack and the vite local dev server.

  • If you face any issues using the cli run the containers one by one.

This brings up Django, a worker node PostgreSQL, Redis and Mailhog. The first time it is run it might take a while to get started, but subsequent runs will occur quickly.

Run the Stack

Open a terminal at the project root and run the following for local development:

text
$ docker-compose up

# or use the shortcut
$ make run

# v0.14.1, in your virtual evn
$ python -m cli dev start

Go to http://localhost:8000 and you should see the default landing page!

Create your first user

The Vanty Starter Kit Sign-up flow works out of the box. By default you can already register and log in as a user.

However for development, it is necessary to create a superuser that will be able to access the Django admin and Control Panel .

We added a modified createsuperuser command that will also create a tenant for the new superuser.

text

$ vanty dev create-superuser

Docker Tips & Tricks

Compose file and environments

By default, docker will always use a docker-compose.yml file in the root of your folder.

text
$ docker-compose up

To run in a detached (background) mode, just:

text
$ docker-compose up -d

Executing Management Commands

As with any shell command that we wish to run in our container, this is done using the docker-compose -f local.yml run --rm command: :

text
 $ docker-compose run --rm django python manage.py migrate

Example of executing migration command in docker.

Docker Compose file

The local environment brings up several containers that are essential for local development. This includes cache, web app, database, worker and mail server containers. That is a lot but docker abstracts that away so that you don't have to do this manually.

We will include a few excerpts from your project's docker-compose.yml and highlight the important bits.

Database service (excerpt local.yml)

text
 postgres:
    build:
      context: .
      dockerfile: ./compose/production/postgres/Dockerfile
    volumes:
      - local_postgres_data:/var/lib/postgresql/data
      - local_postgres_data_backups:/backups
    env_file:
      - ./.envs/.local/.postgres

The environment variables are in the root .env file.

text
# PostgreSQL
# ---------------------------------------------------------------------------
POSTGRES_HOST=postgres
POSTGRES_DB=<your-db>
POSTGRES_USER=<user>
POSTGRES_PASSWORD=<password>

Django and worker service

text
  django:
    build:
      context: .
      dockerfile: ops/compose/local/django/Dockerfile
    image: advantchdemo_local_django
    restart: unless-stopped
    depends_on:
      - postgres
      - mailhog
    volumes:
      - .:/app:z
    env_file:
      - ./.envs/.local/.django
      - ./.envs/.local/.postgres
    ports:
      - "8000:8000"
    command: /start

  worker:
    image: advantchdemo_local_django
   command: python manage.py run_huey -w3
    env_file:
      - ./.envs/.local/.django
      - ./.envs/.local/.postgres
    depends_on:
      - postgres
      - django
      - mailhog
    volumes:
      - .:/app:z

In addition to the web container, the compose file will also bring up worker service for running async tasks. The worker container is a copy of the Django service, except that instead of running a server, it will run a worker task.

Mailhog

When developing locally, you can access the email dashboard on http://localhost:8025 .

Local Tunnels

For local tunnels, we suggest using Cloudflare Tunnel. Cloudflare Tunnel runs a lightweight daemon (`Cloudflare) in your infrastructure that establishes outbound connections (Tunnels) between your origin web server and the Cloudflare global network. In practical terms, you can use Cloudflare Tunnel to allow remote access to services running on your local machine. It is an alternative to popular tools like Ngrok, and provides free, long-running tunnels via the TryCloudflare service.

While Cloudflare Pages provide unique deploy preview URLs for new branches and commit on your projects, Cloudflare Tunnel can be used to provide access to locally running applications and servers during the development process.

Installing Cloudflare Tunnel

Cloudflare Tunnel can be installed on Windows, Linux, and macOS. To learn about installing Cloudflare Tunnel, refer to the in the Cloudflare docs .

Confirm that cloudflared is installed correctly by running cloudflared --version in your command line:

text
$ cloudflared --version

cloudflared version 2021.5.9 (built 2021-05-21-1541 UTC)

Start a Cloudflare Tunnel

With a local development server running, a new Cloudflare Tunnel can be instantiated by running cloudflared tunnel in a new command line window, passing in the --url flag with your localhost URL and port. cloudflared will output logs to your command line, including a banner with a tunnel URL:

text


$ cloudflared tunnel --url http://localhost:3000

2023-07-15T20:11:29Z INF Cannot determine default configuration path. No file [config.yml config.yaml] in [~/.cloudflared ~/.cloudflare-warp ~/cloudflare-warp /etc/cloudflared /usr/local/etc/cloudflared]

2023-07-15T20:11:29Z INF Version 2021.5.9

2023-07-15T20:11:29Z INF GOOS: linux, GOVersion: devel +11087322f8 Fri Nov 13 03:04:52 2020 +0100, GoArch: amd64

2023-07-15T20:11:29Z INF Settings: map[url:http://localhost:3000]

2023-07-15T20:11:29Z INF cloudflared will not automatically update when run from the shell. To enable auto-updates, run cloudflared as a service: https://developers.cloudflare.com/argo-tunnel/reference/service/

2023-07-15T20:11:29Z INF Initial protocol h2mux
2023-07-15T20:11:29Z INF Starting metrics server on 127.0.0.1:42527/metrics
2023-07-15T20:11:29Z WRN Your version 2021.5.9 is outdated. We recommend upgrading it to 2021.7.0

2023-07-15T20:11:29Z INF Connection established connIndex=0 location=ATL
2023-07-15T20:11:32Z INF Each HA connection's tunnel IDs:map[0:cx0nsiqs81fhrfb82pcq075kgs6cybr86v9vdv8vbcgu91y2nthg]
2023-07-15T20:11:32Z INF +---------------------------------------------------------
2023-07-15T20:11:32Z INF |  Your free tunnel has started! Visit it:                    
2023-07-15T20:11:32Z INF |    https://seasonal-deck-organisms-sf.trycloudflare.com     
2023-07-15T20:11:32Z INF +-----------------------------------------------------

In this example, the randomly generated URL https://seasonal-deck-organisms-sf.trycloudflare.com has been created and assigned to your tunnel instance. Visiting this URL in a browser will show the application running, with requests being securely forwarded through Cloudflare’s global network, through the tunnel running on your machine, to localhost:3000 .

Next Steps

Cloudflare Tunnel can be configured in a variety of ways and can be used beyond providing access to your in-development applications. For example, you can provide cloudflared with a configuration file to add more complex routing and tunnel setups that go beyond a simple --url flag. You can also attach a Cloudflare DNS record to a domain or subdomain for an easily accessible, long-lived tunnel to your local machine.