Skip to content

How to Orchestrate a Tmux Development Environment

Developing a modern full-stack application often requires running multiple local servers, maintaining a code editor, and having a general terminal available for CLI commands. To prevent terminal clutter and context switching, we orchestrate a highly efficient development environment using Tmux and a Makefile.

The DevX Workflow

We trigger the entire environment using a single command from the project root:

make dev

What happens under the hood?

When make dev is run, it executes the dev.sh bash script. This script acts as an orchestrator:

  1. Cleanup Phase:
  2. It forcefully kills any pre-existing Tmux session named Crud-in-the-cloud.

  3. It runs lsof -ti:8000,8001,8002 | xargs kill -9 to instantly free up the ports used by Django, FastAPI, and MkDocs. This prevents frustrating "Port already in use" errors.

  4. Session Initialization:

  5. It creates a new, detached Tmux session and provisions 5 distinct, named windows.
  6. Window 1 (Main): A blank shell for running git commands or database migrations.
  7. Window 2 (Nvim): Automatically launches Neovim at the project root (nvim .).
  8. Window 3 (Django): Runs the make django-dev target (Port 8000).
  9. Window 4 (FastAPI): Runs the make fastapi-dev target (Port 8001).

  10. Window 5 (Mkdocs): Runs the make mkdocs-dev target (Port 8002).

  11. Landing:

  12. The script sets the active window back to Nvim (Window 2) so you are immediately ready to code.
  13. Finally, it attaches your terminal to the Tmux session.

Once inside the Tmux session, you use the Tmux prefix (usually Ctrl + b) followed by a key to interact:

  • Switch to a specific window: Ctrl + b then 1, 2, 3, 4, or 5.
  • Go to the next window: Ctrl + b then n.
  • Go to the previous window: Ctrl + b then p.
  • Detach from the session: Ctrl + b then d. This drops you back to your regular terminal, but leaves all servers and Neovim running in the background.

To jump back into the running session later, simply type:

tmux attach

Tearing Down

To completely stop all servers, close Neovim, and destroy the Tmux session, run:

make stop