Getting Started

Getting Started#

Lets start with simple basics first without too many fuzz. LocalDevStack is a modular Docker-based local dev stack orchestrated by the lds CLI and powered by Compose profiles.

Prerequisites#

Install Docker on your system first. If you already have Docker installed, you can skip this step.

Recommended: Docker Engine (Linux) for best performance and lowest overhead.
If Docker Engine is not supported on your OS, use Docker Desktop (Windows/macOS; can also be used on Linux).

Quick Start#

Make lds executable and apply permissions

Linux/macOS:
```
chmod +x ./lds
sudo ./lds setup permissions
```
Notes:
- On Linux, the permissions step is recommended to avoid common volume/UID permission issues.
- On Windows, you typically run the wrapper (example: lds.bat) and may need to add the project root directory to your Environment PATH if you want lds usable from any directory.
Start the stack:
```
lds start
```
Add a domain (generates vhosts and updates stack selection):
```
lds setup domain
```
(Optional) Generate and trust TLS certificates

If you enabled HTTPS vhosts and want browser trust, use the TLS workflow described in:
- TLS and Certificates

Directory Structure#

Recommended project layout#

By default, keep your projects in a sibling directory (simple and predictable):

project-root/
├─ application/
│  ├─ site1/
│  ├─ site2/
│  └─ ...
└─ LocalDevStack/        (this repository)

This layout is flexible. If you want a different projects folder, set PROJECT_DIR in your env.

Example:

PROJECT_DIR=../path/to/your/projects  # supports relative/absolute path (recommended to use absolute path for less confusion)

LocalDevStack layout#

Where things live:

LocalDevStack/
├─ bin/                      # optional helper binaries / shims (Don't touch)
├─ configuration/            # These are created and persisted according to the process you follow (generated automatically)
│  ├─ apache/                # Generated apache vhost configs (if you use apache mode)
│  ├─ nginx/                 # Generated nginx vhost configs (primary entry in most setups)
│  ├─ php/                   # php.ini and php overrides (The php.ini you see here can be modified)
│  ├─ ssh/                   # ssh keys (optional; useful for git over ssh inside containers)
│  ├─ ssl/                   # generated TLS certs (can be used for trusting systemwide)
│  └─ rootCA/                # local CA store (The generated root certificate)
├─ docker/                   # internal stack definition (Don't touch)
│  ├─ compose/               # main.yaml + service fragments (http/php/db/tools/... etc)
│  ├─ conf/                  # container configuration templates/snippets
│  ├─ data/                  # persistent service data (db volumes etc.)
│  └─ logs/                  # container logs (if your stack writes here)
├─ .env                      # Docker only env (generated by tools, Don't touch)
├─ lds                    # main CLI (Linux/macOS) (Don't touch)
└─ lds.bat                # Windows wrapper (Don't touch)

Run the server (the easy way)#

Create or update env files (minimum: profiles + project dir).

Typical locations used by this stack:
- docker/.env (stack settings / profiles)
- .env (project-level env, exposed to your projects)
Start the stack:
```
lds start
```
Add domains via the wizard (recommended):
```
lds setup domain
```

Usage#

Common commands:

lds start
lds stop
lds reload
lds restart
lds rebuild

HTTP utilities:

lds http reload

Shells:

lds core <domain>

Notes:

lds core <domain> is intended to open the right runtime container shell for that domain.

Next steps#

Domain and vhosts: Domain Setup
Local TLS (mkcert + certify): TLS and Certificates
Node apps behind Nginx: guides/node-apps
Encrypted secrets (SOPS + Age): Secrets with SOPS and Age
Notifications: Notifications