Answers to get started

Questions aboutDwell.

What to know before your first project: requirements, workflow and limits. These answers relate to the current repository state.

Getting started and requirements

What does Dwell handle for me?

Dwell supplies reproducible local web project environments: curated Managed stacks or Custom, backend and frontend, Docker runtime, gateway and routing. Application, editor and debugging remain your workflow.

Is Dwell meant to replace DDEV or Lando?

No. Dwell is an additional alternative for local web development, not a complete replacement for DDEV or Lando. Its small Managed scope offers curated standard paths and limits universal infrastructure configuration. When that path fits, you need to model less infrastructure yourself. Custom opens the documented runtime contract to other applications. DDEV offers add-ons and custom Docker Compose services; Lando offers recipes, configurable services, tooling and events. If your project needs a larger individual infrastructure contract, such a tool can be an appropriate choice.

What do I need to install Dwell?

Node.js ≥ 20.19.0, npm in PATH and a running Docker daemon with Linux containers and Compose v2. Frontend profiles may require newer Node versions. Frontend-only also uses the shared Docker gateway.

How do I install the current Release Candidate?

package.json declares 1.0.0-rc.1. The README describes checking out the repository, running npm ci and npm pack, then installing the generated package globally. Follow the installation section; the status is Release Candidate.

Can I use Dwell commercially?

Dwell is covered by GNU GPL version 3 or later, which permits commercial use (e.g. building client projects). However, if you modify and distribute the Dwell source code, you must release your changes under the same conditions (Copyleft). Check the licence file for your version and the licences of its dependencies.

Which stacks are Managed – and why only a few?

Symfony, Laravel, Shopware 6, WordPress and TYPO3 for the backend; React + Vite and Vue + Vite for the frontend. Managed means an integration contract maintained by Dwell. New stacks require relevant demand, a clear runtime model, architectural fit, sustainable maintenance and reproducible tests. Popularity alone is insufficient.

What does Custom mean for Joomla, Next.js, Nuxt or Angular?

Not managed does not mean unusable. Joomla may fit Custom PHP; Next.js, Nuxt and Angular may fit Custom Frontend, without an official framework support guarantee. Dwell provides the generic environment; you maintain the application, installation, packages, versions and production build. Custom frontend commands must honor the loopback host and allocated port.

Projects and workflow

How do I start my first project?

dwell init configures the project. dwell build prepares scaffolds, dependencies and backend images; dwell up starts the environment. Install Custom applications and their dependencies yourself.

Where are configuration and runtime files stored?

The project configuration is in .dwell/dwell.json. Generated runtime files live in .dwell/runtime/. The shared gateway uses ~/.dwell/gateway/. Consult the documentation for your version before making changes.

Can I use Dwell without Docker?

No. Docker is the foundation of the local environment. If you cannot or do not want to use containers, you need another approach.

What does dwell artifact do – does it deploy?

dwell artifact creates separate production files in artifact/; source, manifests and lockfiles remain unchanged. Supported: Managed backends without a frontend and Symfony with React/Vite or Vue/Vite. No upload, deployment or server setup. Production configuration and transfer remain your own workflow.

Can I import existing projects?

dwell import analyzes known files and package metadata and presents a proposal. Review it first with --json. Managed detection is limited; Custom is a controlled path for other applications. Unsupported framework versions are not silently changed. Import moves no application and adopts no foreign Docker setups.

What is dwell handoff for?

After cloning, the command checks local readiness: configuration, versions, tools, directories, host conflicts and declared environment keys. Resolve blockers and supply local values before build and up. It creates no transfer package and transfers no VM, containers or secrets.

Domains, HTTPS and networking

What does dwell access show?

Configured application and tools URLs, without checking availability. The overview hides passwords. dwell access db and dwell access phpmyadmin can include project credentials, but no MariaDB root password. mariadb:3306 is internal, not an automatically accessible host database connection.

Which local domain does my project use?

The local address uses .localhost. Project name, runtime slug and host base can be configured independently. Matching .local names are added when LAN sharing is enabled.

Why must my browser trust the local certificate?

Local HTTPS is optional and requires mkcert and available gateway ports. Clients must trust the certificate issuer. Local HTTP can redirect to HTTPS; LAN HTTP remains available without automatic HTTPS redirection. Use the printed links and check certificate trust on each device.

How do I access my project from a phone?

Enable local sharing with dwell up --lan. The other device needs to be on the appropriate local network and resolve the .local name. Availability depends on the network and mDNS support; sharing is not an internet tunnel.

What should I check if a project does not start?

Use dwell doctor to check local tools, Docker, gateway and configured HTTP routes first. dwell ps and dwell logs help narrow down problems. dwell plan up can preview startup operations and detectable blockers without changing project files or services. Automatic fixes are not guaranteed.

dwell doctor

If something will not start: check first.

Check system requirements, gateway and project routes with dwell doctor. Use diagnostics to narrow down the issue; automatic fixes are not promised. Contact remains available for unresolved questions.