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
-----------

1. 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.

2. Start the stack::

      lds start

3. Add a domain (generates vhosts and updates stack selection)::

      lds setup domain

4. (Optional) Generate and trust TLS certificates

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

   - :doc:`guides/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)
-----------------------------

1. 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)

2. Start the stack::

      lds start

3. 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: :doc:`guides/domain-setup`
- Local TLS (mkcert + certify): :doc:`guides/tls-and-certificates`
- Node apps behind Nginx: :doc:`guides/node-apps`
- Encrypted secrets (SOPS + Age): :doc:`guides/secrets-sops-age`
- Notifications: :doc:`guides/notifications`