Sites
Free & PremiumThe Sites page is where you manage your local websites. Each site ties a folder on your Mac to its own domain and a web server, and optionally to a fixed PHP and Node version and HTTPS. WebDonkey's front proxy listens on ports 80 and 443 and hands every request to the right site. That is why you open a site at https://myproject.test rather than localhost:8080.
What you do here
- Create or edit a site, optionally with a site package such as Shopware 6, WordPress or Laravel.
- Switch sites on and off in the WebDonkey tab and open them in the browser, Finder, a terminal or your editor.
- Run projects that bring their own server, a Node dev server for example: Sites with a serve command.
- Narrow down problems with the site diagnosis.
- Remove a site, optionally together with its database and project folder.
- Test websites from WebDonkey Pages locally: The Pages tab.
- Control your DDEV projects and manage a DDEV project.
- Control your Docker daemon, view container details and logs, start containers and manage images, volumes, networks and Compose projects: Start a container and Docker resources.
Page layout
- Header: the title, a short description and the New site button. The same button sits in the top bar of every page.
- Tabs: WebDonkey, Pages, DDEV and Docker. Each tab shows how many entries it has, 0 included. WebDonkey remembers the tab you picked until you quit the app.
- WebDonkey: your own sites.
- Pages: sites that WebDonkey Pages set up, plus built Pages websites that have no site here yet.
- DDEV: the projects of your DDEV installation.
- Docker: containers, images, volumes, networks and Compose projects of your Docker daemon.
- List: in the WebDonkey and Pages tabs, a table with one row per site, with Total, Active and SSL above it. While the WebDonkey tab has no site yet, it says "No sites yet. Create your first one." with a New site button.
While the form for creating or editing a site is open, the tabs and the list are hidden. Back to sites, Cancel or the Esc key bring them back.
Free and Premium
Sites, the Pages tab, DDEV and Docker are part of Free. On Free, at most three sites use HTTPS at the same time. Premium lifts that limit and unlocks site packages. See SSL certificates and Site packages. Prices are on webdonkey.io/pricing.
The WebDonkey tab Free & Premium
The WebDonkey tab lists every site WebDonkey runs for you, except the websites from WebDonkey Pages. This is where you switch sites on and off, open them in the browser, Finder, a terminal or your editor, and reach every other action of a site.
Where to find it
Sidebar Local › Sites, tab WebDonkey. In the terminal, wd sites lists your sites, see Core commands.
The list
Three numbers sit above the table: Total (every site in the tab), Active (switched on) and SSL (with HTTPS).
| Column | Content |
|---|---|
| Site | The domain, with the document root below it. A green lock means HTTPS, +2 is the number of aliases. Hover the domain to see all aliases. A site you just created carries New until you leave the page. |
| Server | The site's web server: nginx, Caddy or Apache. For a site with a serve command it shows Process with the port and a dot that stays green while the process runs. |
| Runtime | The site's PHP and Node version, each with a coloured dot for its version status. A dash means a static site without PHP or Node. In narrow windows the runtime moves under the server. |
| Status | A switch with Active or Off. If the site's folder no longer exists, it shows Folder missing instead of the switch. |
Actions of a site
Every row has the same buttons in the same places:
- Open in browser: starts what the site needs and opens its domain. What happens is described below.
- Open in Finder: always opens the site's project folder in Finder, whatever the settings say. Without a project folder of its own, that is the document root.
- Open terminal in folder: a shell in the project folder. Where it opens is set under Open with.
- Open in editor: opens the project folder in a code editor. With Automatic, that is the WebDonkey Editor as soon as it is installed, otherwise the app set under Open code in.
- Edit (pencil): opens the form with all values of the site, see Create and edit a site.
- More actions (…): the menu with the less frequent actions.
In narrow windows, Open in Finder, Open terminal in folder and Open in editor move into the More actions menu.
The More actions menu
- For a site with a serve command, Restart process and Stop process come first. If the process is stopped and the site is on, it shows Start process instead. See Sites with a serve command.
- Run diagnosis: checks the chain from the browser to the file, see Site diagnosis.
- Regenerate cert + vhost: rewrites the site's web server configuration, reissues its certificate if it uses HTTPS, and reloads the web servers and the front proxy. This helps when a configuration file was changed by hand.
- Remove site: opens the removal dialog, see Remove a site.
How to do it
Switch a site off
- Click the switch in the Status column of the site's row.
- The column shows Off and the domain is released.
Click the switch again to turn it back on. WebDonkey then writes the configuration again and starts what the site needs.
Open a site in the browser
- Click Open in browser in the row.
- WebDonkey starts the services needed and opens the domain in your default browser, with
https://if the site has SSL,http://otherwise.
What happens in the background
Switching off removes the site's web server configuration, releases its domain and syncs the entries in /etc/hosts. Your files stay as they are.
Open in browser works like this:
- Start PHP-FPM in the site's version if it uses PHP, and its web server if that is not running yet.
- Start only the database servers the site's configuration points at, its
.envorwp-config.phpfor example. If the configuration names no database at all, WebDonkey starts every database server installed in WebDonkey. If another program holds a database server's port, WebDonkey leaves that one out. - Rewrite the site's configuration and make sure the front proxy serves ports 80 and 443.
- Open the domain in the browser.
For a site with a serve command, WebDonkey starts its process instead of PHP and a web server. When you change a site's domain, aliases or SSL, WebDonkey updates the web server configuration, the certificate and name resolution itself when you save.
Free and Premium
On Free, at most three sites have SSL at the same time. The rest of the list and every action are part of Free. See SSL certificates.
Troubleshooting
| What you see | Why | What to do |
|---|---|---|
| Message "Site could not be started" | The site's web server or PHP version is missing or does not start. The message names the web server. | Install or start the web server and PHP under Services, then open the site again. If that does not help, run the site diagnosis. |
| Message that port 80/443 forwarding could not be enabled | The front proxy does not serve ports 80 and 443. Without it, sites are only reachable with a port. | Read the reason below the message. In the diagnosis, the line about the front proxy shows whether it runs. |
| Folder missing in the Status column | The document root was deleted or moved. The switch and the folder buttons are locked for that reason. | Pick another folder under Edit, or remove the site. |
| Message "The site has been created, but its services did not start" | A service did not start when the site was created. The site stays off for now. | Fix the cause named in the message and switch the site on. |
| Error with Retry instead of the list | The list of sites could not be read. | Click Retry. |
See also
Create and edit a site Free
A site ties a folder on your Mac to a domain and a web server, and optionally to PHP, Node and HTTPS. New site creates one, Edit changes it later. Both use the same form, which takes up the whole Sites page.
Where to find it
- Sites page: New site at the top right. While there is no site yet, the button also sits in the middle of the empty list.
- Every page: New site in the top bar.
- An existing site: Edit (pencil) in its row.
- In the terminal,
wd sites create <domain>creates a site for the current folder, see Core commands.
How to do it
- Click New site.
- Under Site package (optional), keep No package or pick a package, see Site packages.
- Under Address, enter a Name and a Domain, for example
myproject.test. - Under Folder & serving, pick the Document root, either as a path or with Select.
- Under Server & runtime, pick the Web server and, if needed, PHP version (optional) and Node version (optional).
- Keep SSL via local WebDonkey CA ticked if the site should run on
https://. - Click Create at the bottom.
The form closes and the WebDonkey tab shows the new site marked New.
Every site needs four things: Name, Domain, Document root and Web server. While one is missing, its field has a dot at the label and a coloured frame, the bottom bar says "Still needed: …", and Create stays disabled.
Edit a site
- Click Edit in the site's row.
- The form is now called Edit site and shows the domain below the title. There is no site package section when editing.
- Change what you need, including the web server, PHP version or domain.
- Click Save.
WebDonkey rewrites the web server configuration. A changed domain gets a new certificate and new name resolution entries.
Close the form
Back to sites, Close (Esc), Cancel and the Esc key close the form. If you have entered something, WebDonkey asks "Discard your input?". Keep editing leaves everything in place, Discard throws the input away. While a site package is installing, the form cannot be closed.
If you switch to another page with the form open, to start a database under Services for example, the half-filled form stays as it is. When you come back to the window, the form checks again which web servers and PHP and Node versions are installed, so it also sees what you installed in a terminal in the meantime.
Fields and options
Site package (optional)
Only when creating. The No package tile creates an empty site for a project you bring yourself. The other tiles install an application right away. A chosen package decides which runtime fields appear further down and which versions fit there. Site packages are Premium, details under Site packages.
Address
| Field | Meaning |
|---|---|
| Name | The display name in WebDonkey. Required. |
| Domain | Required. Letters, digits and hyphens, with at least one dot and an ending, such as shop.dev or client.local. You choose the ending freely. If the spelling does not fit, it says "Letters, digits and hyphens, with an ending, e.g. myproject.test" below. |
| Aliases (optional, comma-separated) | More domains for the same site, separated by commas or spaces. They are included in the certificate. |
WebDonkey does not accept a bare ending like test as a domain, because it would then send every address below it to your Mac. Put a name in front, such as myproject.test.
Folder & serving
| Field | Meaning |
|---|---|
| Document root | The folder the web server serves. Required. Select opens the folder picker, a leading ~/ is fine. A framework package sets it to the right subfolder, such as public/, after the install. |
| Project folder | Optional: where the code lives if not in the document root, for example the folder above public/. The folder, terminal and editor buttons open it. Scheduled tasks, workflows, the AI's working folder and the search for a site's database use it too. Left empty, the document root applies. |
| Serve command | Leave empty for a normal site. Filled in, with npm start for example, that process serves the site instead of a document root. The first field is then called Project folder, the second project folder field disappears, and Port appears. See Sites with a serve command. |
| Port | Only with a serve command. Left empty it stays automatic, and WebDonkey picks a free port. |
Server & runtime
| Field | Meaning |
|---|---|
| Web server | Required. The list shows the installed web servers with version and source, the first one is preselected. You pick it per site, independently of other sites. If none is installed, it shows "(none installed)" with a pointer to the Services page. |
| PHP version (optional) | The site runs on exactly this installed PHP version. (none) means a site without PHP. Below the field you see the version status of the chosen version, and in the list other versions carry EOL or Recommended. Below that comes the database host hint (see below). |
| Node version (optional) | A Node version installed by WebDonkey, or (none). If a package needs Node and there is a Node outside WebDonkey on the Mac, System Node (…) is offered as well. |
| SSL via local WebDonkey CA | Issues a certificate from the local certificate authority and turns HTTPS on. For a new site it is ticked on Premium and unticked on Free. On Free it shows how many sites use SSL, such as "2/3 sites with SSL". |
With a site package, the runtime fields read like "PHP version (Shopware 6 needs …)". Versions that do not fit are greyed out and say "does not fit …". If the package does not use a runtime at all, its field is not shown.
Package settings
With a package chosen, the Settings for … section follows with the package's fields, see Site packages.
Tip: database host in your code
When you put a database host into a site's code, use 127.0.0.1 with port 3306 (MySQL) or 3307 (MariaDB), not localhost. With localhost, PHP looks for a socket file that WebDonkey's database servers do not use.
What happens in the background
When you create a site, WebDonkey writes the configuration for the chosen web server and the front proxy, issues the certificate if SSL is on, and adds the domain and aliases to name resolution. Then it starts what the site needs. If a service does not start, the site stays switched off and a message names the reason.
With Tools in the terminal turned on in the settings, php and node use the site's versions inside its project folder and its subfolders.
Free and Premium
- Site packages are Premium. On Free, the site package section is locked and carries the Premium badge.
- On Free, at most three sites have SSL at the same time. Once that limit is reached, SSL via local WebDonkey CA is locked and carries the Premium badge. Premium lifts the limit.
Troubleshooting
| What you see | Why | What to do |
|---|---|---|
| A hint below the Domain field | The spelling does not fit: spaces, special characters, no dot, or a hyphen at the edge of a part. | Use only letters, digits and hyphens, with an ending. |
| Message that the domain is a whole ending | You entered an ending like dev or co.uk as the domain. |
Put a name in front, such as myproject.dev. |
| "(none installed)" for the web server | No web server is installed yet. | Install nginx, Caddy or Apache under Services. The form stays open. |
| The SSL checkbox is locked | On Free, three sites already have SSL. | Turn SSL off on another site, or use Premium. |
| Error message below the form | Creating failed, for example because another site already uses the domain. | Read the message and change the value. |
See also
Site packages Premium
A site package installs a whole application while you create a site: Shopware, WordPress, a framework or a frontend scaffold, including database, configuration and the right document root. You pick it in the New site form under Site package (optional). Site packages are a Premium feature.
Where to find it
Sites page › New site, first section Site package (optional). The section does not exist when you edit an existing site. In the terminal, wd sites create <domain> --package <package> installs a package and wd sites packages lists them all.
How to do it
- Click New site and pick a tile under Site package (optional), such as Shopware 6.
- Check under Requirements that everything is there. Install what is missing with Install now or Set up.
- Fill in Address, Folder & serving and Server & runtime as for any site, see Create and edit a site. An empty folder is the best document root.
- Check the fields under Settings for …, such as the database name and the admin password.
- Click Create. WebDonkey first checks the folder and the database ("Checking folder and database…").
- The install runs. A box shows "Installing package …", the step ("Step 3 / 9") and the output live.
- When it is through, click Done. The new site is in the list.
The packages
| Package | What WebDonkey installs | Document root |
|---|---|---|
| Static website (HTML) | an index.html with the site title |
the chosen folder |
| PHP (empty project) | an index.php, optionally with a MySQL or MariaDB database (Create database) |
the chosen folder |
| WordPress | database, WP-CLI (checked against its checksum), WordPress, wp-config.php, install with an admin user, the Twenty Twenty-Four theme |
the chosen folder |
| Shopware 6 | database, composer create-project shopware/production, .env.local with database, APP_URL and Mailpit as mailer, system:install with language, currency and shop name, an admin password for the user admin, optionally demo data and the compiled storefront theme |
public/ |
| Laravel | composer create-project laravel/laravel, .env with database and Mailpit, APP_KEY, migration, storage link |
public/ |
| Symfony | skeleton plus webapp pack, .env.local with APP_SECRET, DATABASE_URL and Mailpit as mailer |
public/ |
| Drupal | database, drupal/recommended-project, Drush, site:install with the chosen profile, settings for the front proxy |
web/ |
| Vite (React / Vue / Vanilla) | scaffold with the chosen template, npm install, build |
dist/ |
| Astro (static) | scaffold with the chosen template, npm install, build |
dist/ |
| Angular | a new project with the Angular CLI, build | dist/app/browser/ |
| Hugo | a minimal layout with two content pages, build with hugo --minify |
public/ |
With Vite, Astro and Angular the web server serves the built result, no Node server runs. When the document root is set to a subfolder, the previous folder becomes the site's project folder.
Fields and options
Requirements
What a package needs is fixed and shows up as soon as you pick it. Each row states its condition:
| Row | Possible states |
|---|---|
| Database | a choice of engine (MySQL or MariaDB) and its version. "running", "stopped, starts when the site is created" or "Not installed." with Install now. Also host and port, such as "Host 127.0.0.1, port 3306". |
| PHP | whether an installed version falls within the package's range. Otherwise something like "8.1.31 is installed but does not fit Shopware 6 (needs …)." |
| PHP extensions | "All 23 loaded in PHP 8.4", or which are missing. Where WebDonkey can load an extension itself, Set up sits next to it. |
| memory_limit | the value of the chosen PHP version. If it is too low, Set up changes WebDonkey's php.ini for that version and restarts it if it is running. |
| Node.js | whether an installed version fits, otherwise Install now. |
| Tools | such as Composer or Hugo, with Install now. |
While something is still missing, Create stays disabled and the bottom bar says something like "Shopware 6 still needs: PHP extensions (install above)." Create is also disabled while WebDonkey is still checking the requirements ("Checking…").
Settings for …
The package's fields with sensible defaults. The database name follows the domain until you change it yourself, so two shops do not end up with the same database. Show password fields with Show and hide them with Hide. Version fields such as Shopware version (live from Packagist) load the versions when they open ("Loading versions…"). Other… lets you enter your own value.
| Package | Fields |
|---|---|
| Shopware 6 | Shop name, Subfolder in the DocRoot (optional), Shopware version (live from Packagist), Database name, Database user, Database password, Default currency (EUR, USD, GBP, CHF), Language / locale, Admin password, Install demo data, Compile storefront theme |
| WordPress | Site title, Admin username, Admin password, Admin email, database name, user and password |
| Drupal | Site name, Admin username, Admin password, Install profile (Standard or Minimal), database name, user and password |
| Laravel | Laravel version (live from Packagist), Database (SQLite without a server, MySQL or MariaDB) and, with MySQL or MariaDB, name, user and password |
| Symfony | Database (SQLite, MySQL or MariaDB) with name, user and password |
| PHP (empty project) | Create database, then engine, name, user and password |
| Vite (React / Vue / Vanilla) | Template: React, Vue, Vanilla, Svelte or Preact, with or without TypeScript |
| Astro (static) | Template: Minimal, Basics or Blog |
| Angular | Angular version, Stylesheets (CSS, SCSS, Sass, Less, Tailwind CSS), Change detection, Tests, Routing |
| Static website (HTML), Hugo | Site title |
For a package that must have a database, you pick the engine under Requirements. It is not repeated further down.
What happens in the background
- WebDonkey creates the site first, then runs the package's steps one by one. The package starts stopped services it needs by itself.
- The database is created and the chosen user gets the rights it needs.
- If the folder already has files the package would replace, WebDonkey lists them on the first click on Create (up to eight, then "and … more"). It keeps no copy. Pick an empty folder or click Replace and create.
- WebDonkey never overwrites a database that has tables. It stops beforehand and asks for a different database name.
Free and Premium
Site packages are Premium. On Free, the section shows the Premium badge and the note "Site packages are a Premium feature.", and the tiles are locked. Empty sites without a package are unlimited on Free. Prices: webdonkey.io/pricing.
Troubleshooting
| What you see | Why | What to do |
|---|---|---|
| "This folder already has files the template would replace:" | The folder is not empty. | Pick an empty folder, or click again (Replace and create). |
| "The database "…" is not empty" | A database with tables already exists under that name. | Enter a different database name. |
| "Stopped before anything changed" in the log | The folder already had files when the install started. | Pick an empty folder. |
| "Installing package (error)" | A step failed. The log shows its output. | Read the output, fix the cause and leave the form with Close. The site already exists and can be removed or set up again. |
| A PHP extension "is not part of this PHP … build" | The chosen PHP version was built without that extension. | Pick another PHP version, or add the extension yourself, with PECL for example. |
See also
Sites with a serve command Free
Some projects bring their own server, a Node project with npm start for example, or the dev server of Next.js or Vite. For those you enter a Serve command. That long-running process then serves the site instead of a document root, and the front proxy forwards requests to its port. The domain with HTTPS stays the same as for any other site.
Where to find it
The New site or Edit form, section Folder & serving, field Serve command. Afterwards you control the process in the WebDonkey tab through the site's More actions menu.
How to do it
- Open New site and enter Name and Domain.
- Under Serve command, enter the command that starts the server, for example
npm start. - The first field is now called Project folder. Pick the folder the command should run in, where the
package.jsonlives. - Leave Port empty (automatic) or enter a fixed port.
- Pick a Web server. The form requires one, but the site does not use it.
- Click Create. WebDonkey starts the process and waits until it answers on its port.
Fields and options
| Field | Meaning |
|---|---|
| Serve command | Empty for a normal site. Filled in, WebDonkey starts this command as the site's process. If you clear the field later, the site becomes a normal site with a document root again. |
| Project folder | The folder the command runs in. This kind of site has no second project folder field. |
| Port | Left empty, WebDonkey picks a free port between 3000 and 3199 and keeps it for the site. The process receives it as the PORT environment variable. |
Controlling the process
In the list, the Server column shows Process with the port instead of a web server. The dot in front of it is green while the process runs. Hover it to see Process running or Process stopped and the command.
The site's More actions menu offers:
- Restart process and Stop process while the process runs.
- Start process when it is stopped and the site is on.
A running process also appears in the Active services menu in the top bar and under Also running on the Services page. If the last start failed, the reason appears in the row below the domain.
What happens in the background
- The process gets the environment variables
PORT(its port),HOSTandHOSTNAME(both127.0.0.1). - WebDonkey starts it through the same supervisor as the services. It runs in a process group of its own, its output goes to a log file, and after an app crash WebDonkey cleans up leftover processes on the next start.
- After the start, WebDonkey waits up to 60 seconds for the port to answer. Only then does the start count as done, and Open in browser opens the domain. That way you do not land on a proxy error page during a long first build.
- A site like this needs neither PHP-FPM nor a web server. WebDonkey starts neither for it.
- When the app starts the next time, WebDonkey restarts the processes of all enabled sites with a serve command, one after another.
Free and Premium
Site processes do not take one of Free's six service slots. Sites with a serve command are part of Free.
Troubleshooting
| What you see | Why | What to do |
|---|---|---|
| Reachable on Wi-Fi (Wi-Fi icon next to the port) | The server listens on every network interface instead of only 127.0.0.1. Devices on the same Wi-Fi reach it directly on the port, past WebDonkey's proxy. |
Bind the server to 127.0.0.1, for example with --host 127.0.0.1 or by letting it read HOST or HOSTNAME from the environment, and restart it. |
| A message that the process has exited | The command stopped right after starting. The message names the log file with its last output. | Read the log. Often dependencies are missing (npm install) or the folder is wrong. |
| A message that the site does not listen on its port after 60 seconds | The process runs, but on a different port. | Make the command read its port from PORT, or enter the port in the form. |
| A banner says the site cannot start because its port is in use | Another program holds the port. | Free port … in the banner stops that program and restarts the site. Or enter a different port. |
See also
Site diagnosis Free
The Site diagnosis checks every layer between the browser and the file and shows where things break. If a site does not load, the browser warns about the certificate, or the wrong page answers, it finds the broken link in the chain within seconds.
Where to find it
Sites page, the site's row › More actions (…) › Run diagnosis. In the terminal, wd sites diagnose checks the same chain.
How to do it
- Open the More actions menu in the site's row and choose Run diagnosis.
- The Site diagnosis dialog ("Checks every layer between browser and file") briefly shows "Checking…" and then the results.
- Each line has a green check or a red cross, with details below where useful, such as a path or an error message.
- Fix the first red line and click Check again.
- Close ends the dialog.
The names of the checks come from WebDonkey's core and may appear in German.
What is checked
In this order, with the SSL and nginx lines only where they apply to the site:
| Check | What a red line means |
|---|---|
| The document root exists | The site's folder does not exist. |
An index file is present (index.html or index.php) |
There is no start file in the document root. With frameworks, the document root often points at the wrong folder. |
/etc/hosts has an entry for the domain |
The domain does not point at your Mac. |
| The front proxy is active on 80/443 | Without the proxy, no domain reaches its site. |
| The site's web server is running | nginx, Caddy or Apache is stopped. |
| The PHP-FPM socket for the site's PHP version | PHP is not running in that version. |
| The vhost file has been generated | The site's web server configuration is missing. |
| An SSL certificate has been issued (SSL only) | There is no certificate for the site. |
| HTTPS port 443 accepts connections (SSL only) | The proxy does not accept HTTPS connections. |
nginx -t (nginx only) |
The nginx configuration has an error, the details name it. |
When something is red
| Red line | What to do |
|---|---|
| Document root or index file | Pick the right folder under Edit, such as public/ for frameworks. |
| Web server or PHP-FPM | Start the service under Services, or let Open in browser start it. |
Vhost file, certificate or nginx -t |
More actions › Regenerate cert + vhost, see The WebDonkey tab. |
| Hosts entry | Switch the site off and on again with its switch. WebDonkey syncs /etc/hosts in the process. |
| Front proxy or port 443 | Check in the Active services menu whether the front proxy runs. If the front proxy fails to start, a banner at the top of the window names the reason. |
| The browser warns although every line is green | The root CA is not trusted yet, see Trust the root CA. |
See also
Remove a site Free
Remove site takes a site out of WebDonkey: web server configuration, SSL certificate, hosts and DNS entries and its runtime directory. Your project files stay where they are. If you want to clean up more, the dialog can take the linked database and the project folder along, the folder only into the Trash.
Where to find it
Sites page, the site's row › More actions (…) › Remove site. In the terminal, wd sites delete <site> only removes the configuration, never the database or the folder.
How to do it
- Open the More actions menu in the site's row and choose Remove site.
- The Remove site? dialog names the domain and the project folder.
- Tick one or both checkboxes if you need them (see below). Both start unticked.
- Click Remove.
The site disappears from the list. If something you ticked could not go along, a message names the reason afterwards. The site itself is removed in any case.
Fields and options
| Checkbox | What it does |
|---|---|
| Also delete the linked database … (…) | Deletes the database the site's configuration names, in .env or wp-config.php for example, on a WebDonkey database server (MySQL, MariaDB or PostgreSQL). The label shows its name and engine. The checkbox only appears if WebDonkey finds such a database. |
| Move the project files to the Trash | Moves the project folder to the Trash, its path is shown below. You can put it back from there. Without a project folder of its own, that is the document root. With the checkbox ticked, the dialog text changes to match. |
What WebDonkey refuses
Some things may not go along. Then the checkbox is greyed out with the reason below it. WebDonkey checks again when you click Remove.
| Reason below the checkbox | Meaning |
|---|---|
| "The database server is not running." | Start the server under Services and open the dialog again. |
| "The database server has no database by this name." | The configuration names a database that does not exist. |
| "It belongs to the database server itself." | WebDonkey never deletes system databases such as mysql. |
| "Also used by the site …." | Another site uses the same database or the same folder. |
| "The folder does not exist." | The project folder is already gone. |
| "This is your home folder or a folder above it." | The folder is too high up in the file system. |
| "macOS needs this folder." | System folders and folders such as Desktop, Documents or Downloads themselves. A project inside them may go. |
| "This is your sites folder from the settings, or it contains it." | The folder your sites live in stays. |
| "The folder belongs to WebDonkey Pages." | WebDonkey Pages manages its websites itself. |
What happens in the background
- WebDonkey removes the web server configuration, the site's certificate, its entries in
/etc/hostsand the local DNS, and its runtime directory. This cannot be undone. - The database is only deleted with the checkbox ticked, and then for good.
- The project folder only goes to the Trash with the checkbox ticked, never straight into oblivion.
- When you remove a site that WebDonkey Pages set up, its website shows up again under From WebDonkey Pages in the Pages tab.
Troubleshooting
| What you see | Why | What to do |
|---|---|---|
| "The site was removed, but the database … could not be deleted" | Deleting the database failed, the reason is in the message. | Delete the database by hand under Databases. |
| "The site was removed, but its project folder could not be moved to the Trash" | The folder is locked or permissions are missing. | Move the folder to the Trash yourself in Finder. |
| "The site could not be removed" | Removing failed, the reason is included. | Fix the cause and try again. |
See also
The Pages tab Free
The Pages tab collects the websites you build with WebDonkey Pages as local test sites. WebDonkey serves a website's built state with PHP under a domain of its own, so you can test it on your Mac, contact form included, before it goes online. Websites you have already built in Pages but not set up here yet take a single click.
Where to find it
Sidebar Local › Sites, tab Pages. The number on the tab counts the sites set up and the websites waiting to be set up. In WebDonkey Pages, Test in WebDonkey creates such a site, see Test in WebDonkey.
What the tab shows
- The list: every site WebDonkey Pages set up, in the same table as in the WebDonkey tab. Each carries the Pages badge ("Set up by WebDonkey Pages").
- From WebDonkey Pages: below it, the websites built in Pages but not set up here yet ("Built in WebDonkey Pages, not set up here yet."). Each row shows the website's name and its future address.
- Empty: if there is neither, it says "No websites from WebDonkey Pages yet. In Pages, "Test in WebDonkey" brings a website here."
How to do it
Set up a built website locally
- Open the Pages tab.
- Find the website under From WebDonkey Pages.
- Click Set up locally. The tooltip says what happens, for example "Sets up my-company.pages with PHP and starts it."
- The website moves into the list above, switched on and running. Open in browser opens it.
Back to Pages
- In the list: More actions (…) › Open in Pages.
- Under From WebDonkey Pages: Open in Pages in the website's row.
WebDonkey Pages then opens with that website.
Address, folders and runtime
| What | Value |
|---|---|
| Domain | The address WebDonkey Pages sets for the website. Without one of its own, it is the website's short name with the .pages ending, such as my-company.pages. When Pages changes the address, the site moves along, including certificate and name resolution. |
| Document root | The website's built state in the .pages/dist folder. |
| Project folder | The website's folder under ~/WebDonkey Pages/ with its code. The folder, terminal and editor buttons open it. |
| Web server | nginx |
| PHP | the active PHP version, so the website's contact form works |
| SSL | on as long as Free's limit allows it, otherwise without |
Apart from that, a Pages site is a normal site: you switch it on and off, edit it, run the diagnosis and see its runtime with its version status.
What happens in the background
- WebDonkey only reads the
~/WebDonkey Pagesfolder. It writes nothing into it. - A website counts as built when its folder has a
website.jsonand a built state with.pages/dist/index.html. - When you remove a Pages site, the website's folder stays. WebDonkey cannot move it to the Trash because it belongs to WebDonkey Pages. The website then shows up again under From WebDonkey Pages.
Free and Premium
The Pages tab is part of Free. On Free, a newly set up Pages site only gets SSL while fewer than three sites use SSL.
Troubleshooting
| What you see | Why | What to do |
|---|---|---|
| "WebDonkey Pages could not be opened. Is the app installed on this Mac?" | WebDonkey Pages is not on the Mac. | Download Pages under Services in the WebDonkey group, see The WebDonkey apps. |
| Error below a website after Set up locally | Setting it up failed, for example because PHP or nginx is missing or the address is taken. | Read the message, install what is missing under Services and set it up again. |
| The website is missing under From WebDonkey Pages | It has not been built in Pages yet, or a site for it already exists. | Build the website in Pages, or look for the existing site in the list. |
See also
The DDEV tab Free
DDEV runs PHP projects such as Shopware, Laravel or WordPress in Docker containers. With DDEV installed, your DDEV projects appear in the DDEV tab next to your WebDonkey sites. You start and stop them here, open them in the browser or in a terminal inside their container, and manage configuration, snapshots, logs and add-ons. Projects you create in the terminal with ddev config show up by themselves.
Where to find it
Sidebar Local › Sites, tab DDEV. The number on the tab is the number of projects. While the tab is open, WebDonkey asks for the current state every six seconds, otherwise every 30 seconds.
When DDEV is missing
Without DDEV the tab shows DDEV is not installed with a short explanation and three buttons:
- Install: installs DDEV through Homebrew. If Homebrew is missing, WebDonkey sets it up first. The running output is shown below.
- About DDEV: opens ddev.com.
- Check again: looks for DDEV again, for example after you installed it in a terminal.
DDEV needs a Docker daemon, such as Docker Desktop, OrbStack or Colima. If the docker command is missing, a note about it already shows here, see The Docker tab.
The list
Above the table you see "Manage your DDEV projects: configuration, snapshots, logs and add-ons.", the numbers Total and Running, and the New project button.
| Column | Content |
|---|---|
| Project | Name and folder of the project. A click opens its management below the row, see Manage a DDEV project. |
| Type | The project type, such as shopware6, laravel or wordpress. |
| Address | The project's address, in wide windows only. |
| Status | A switch to start and stop with Running, Off or Paused. In-between states such as starting are shown as DDEV reports them. |
Actions of a project
- Open in browser: opens the project's address while it runs.
- Show project folder: opens the folder. In narrow windows the button moves into the More actions menu.
- Open a terminal inside the container: a shell in the web container while the project runs. Where it opens is set under Open with. With WebDonkey (built-in terminal) it opens as a tab on the SFTP / SSH page.
- More actions (…): Restart (only while it runs) and Delete.
Delete asks first ("Remove DDEV project") and removes the project from DDEV: containers, volumes and database are deleted. The project folder stays untouched.
New project
New project opens the Set up a DDEV project dialog. It turns an existing folder into a DDEV project.
| Field | Meaning | Default |
|---|---|---|
| Project folder | The folder with your code, typed in or picked with Choose…. Required. | empty |
| Project name | The name in DDEV. Required. When you pick the folder, WebDonkey suggests the folder name in lower case. | folder name |
| Project type | One of the types DDEV knows, such as php, shopware6, laravel, drupal11, typo3, wordpress. |
php |
| Document root | The subfolder the web server serves, such as public. |
empty |
| PHP version | 5.6 to 8.5 | 8.3 |
| Web server | nginx-fpm, apache-fpm or generic |
nginx-fpm |
| Database | mariadb, mysql or postgres |
mariadb |
| Database version | the versions of the chosen database | 10.11 |
| Start right away | starts the project after setting it up | on |
The PHP and database versions carry EOL or Recommended from the version status in the list. Click New project to create it.
What happens in the background
- WebDonkey drives DDEV through its own
ddevcommand. The projects stay ordinary DDEV projects that you can use in the terminal just the same. - While no Docker engine is running, the tab shows a line about it. If an engine is installed, Start … starts it in the background without opening a window. If Docker Desktop is waking up from Resource Saver mode, the projects appear by themselves as soon as the engine answers.
- Where needed, WebDonkey adds the addresses of DDEV projects to
/etc/hostsitself. macOS asks for your administrator password once for that.
Free and Premium
The DDEV tab is entirely part of Free. DDEV projects do not count towards Free's six services.
Troubleshooting
| What you see | Why | What to do |
|---|---|---|
| Folder deleted or Configuration missing instead of the switch | DDEV still lists the project, but its folder or its .ddev/config.yaml is gone. It can no longer be started. |
Delete the project from DDEV in the More actions menu. |
| A message that the addresses do not resolve | Many routers block DNS answers that point to your own Mac. | Start the project again and confirm the macOS password prompt. WebDonkey then adds the addresses to /etc/hosts. |
| A message that DDEV needs a newer docker-buildx | Docker Desktop ships an older version, and setting up a newer one failed. | Check the internet connection and start again, or update Docker Desktop. |
| "DDEV reports: …" about the Docker runtime | Your Docker runtime is older than DDEV will require. The projects still start. | Update Docker Desktop or your Docker runtime soon. |
| The switch does not turn on | No Docker daemon is running. | Start the engine from the line above, or start it yourself and click Check again. |
See also
Manage a DDEV project Free
Clicking the name of a DDEV project opens its management right below the row. It has five tabs: Configuration, Snapshots, Logs, Add-ons and Command. With them you edit the project's config.yaml, back up and swap its database, read its logs, add services such as Redis and run commands in the container.
Where to find it
Sites page, DDEV tab, click the name of a project. A second click closes it again. WebDonkey remembers the open project and the chosen tab until you quit the app. Projects whose folder is missing cannot be opened.
Configuration
The form edits the project's config.yaml. Its path is shown above the form.
| Field | Meaning |
|---|---|
| Project type | The type DDEV sets the project up for. |
| Document root | The folder the web server serves. |
| PHP version | 5.6 to 8.5. The list shows EOL or Recommended, and below the field you see the version status of the chosen line. |
| Web server | nginx-fpm, apache-fpm or generic. |
| Database | mariadb, mysql or postgres. When you switch the database, the version jumps to the newest of the new database. |
| Database version | The versions of the chosen database, with version status. |
| Composer version | such as 2. |
| Node.js version | such as 22, with version status. |
| Additional host names | more host names for the project, comma-separated, such as staging, preview. |
| Additional domains | more full domains, comma-separated, such as example.test. |
| Enable Xdebug | turns Xdebug on for the project. |
Edit as YAML switches to the raw text of the file, Back to form switches back.
- Change the values and click Save.
- WebDonkey reports "Saved. Restart the project for the changes to take effect."
- Click Restart.
The form and the YAML are two separate versions. Only the view you are in is saved. If you switch with unsaved changes, WebDonkey asks "Discard unsaved changes?" and only switches after Switch anyway. The previous version of the file is kept as config.yaml.wd-backup. If the file changes outside WebDonkey, the form shows the new content after the next reload.
Snapshots
Snapshots capture the project database. Restoring replaces the current database.
- Create snapshot: backs up the database now. In the field in front of it you can give it a name ("Name (optional)").
- Restore: after a confirmation, replaces the current database with the snapshot's state.
- Trash icon: deletes a snapshot for good after a confirmation.
- Export database: saves the database to a file,
<project>.sql.gzis suggested. - Import database: replaces the database with the contents of a file (
.sql,.gz,.zipor.tar). WebDonkey asks "Import database?" first.
Each snapshot shows its date and size. Without snapshots it says "No snapshots yet."
Before every import, WebDonkey takes a snapshot of the current database. Afterwards it reports "Imported. The previous database is kept as snapshot "…".", and you can bring the old state back with Restore if needed. If that snapshot fails, WebDonkey does not import.
Logs
Shows the last lines of one of the project's services and reloads them every five seconds.
- First list: the service, such as
web,dbor a service from an add-on. - Second list: 50, 200, 500 or 1000 lines, 200 by default.
- Refresh reloads right away.
Without output it says "No log output."
Add-ons
Add-ons add extra services to the project, Redis or Elasticsearch for example.
- The list shows the installed add-ons with their repository. The trash icon (Remove add-on) takes an add-on and its service out again after a confirmation.
- Enter an add-on in the Name or owner/repo field and click Install.
- Below it, the official add-ons that are still missing sit as quick buttons, such as + redis, + memcached, + elasticsearch, + solr, + mongo, + varnish, + adminer, + phpmyadmin, + cron, + beanstalkd and + proxy-support.
Command
Runs a command in the project's web container, such as composer install. Type it and click Run or press Return. The output appears below, or "(no output)" if there is none. For longer work inside the container, Open a terminal inside the container in the project's row is the better choice.
Troubleshooting
| What you see | Why | What to do |
|---|---|---|
| A red message in the tab | DDEV refused the command, the message shows its output. | Read the output, often the Docker daemon is not running. |
| "The database was not imported: WebDonkey could not take a snapshot of the current database first." | The backup before the import failed. | Check that the project is running and import again. |
| Configuration changes have no effect | The project still runs with the old version. | Restart. |
See also
The Docker tab Free
The Docker tab shows what your Docker daemon holds right now: containers, images, volumes, networks and Compose projects. You start and stop containers, open them in the browser or a terminal, read their logs and clean up what is unused. WebDonkey uses the docker command for this, whichever app provides the daemon: Docker Desktop, OrbStack, Colima and Rancher Desktop are all recognised.
Where to find it
Sidebar Local › Sites, tab Docker. The number on the tab is the number of containers.
When Docker is missing or asleep
- Docker is not installed: the tab explains what it is for and offers Download Docker Desktop (opens Docker's page) and Check again. After the install, start Docker once and click Check again.
- Colima without the
dockercommand: Colima does not ship it. Then you see Install the Docker CLI, which installs it through Homebrew. - OrbStack without the
dockercommand: start OrbStack once, and it sets up the command itself. - No engine running: a line says "No Docker engine is running right now.", with a Start … button for each installed engine. The engine starts in the background without opening a window. The containers appear as soon as it is ready.
- Docker is waking up: if Docker Desktop is coming out of Resource Saver mode, the line says so. You do not need to do anything.
Tab layout
At the top you choose between Containers, Images, Volumes, Networks and Compose, each with its count. Next to them you see how much space can be freed (Reclaimable: …) and a refresh button. WebDonkey reloads the resources every 15 seconds. Images, volumes, networks and Compose are described in Start a container and Docker resources.
Containers
Above the table you see Total, Running and the Start container button.
| Column | Content |
|---|---|
| Container | Name, with the image and status as Docker reports it below. A click opens Details and Logs, see Container details and logs. |
| Ports | The published ports. Clicking a port opens http://localhost:<port>. |
| Status | A switch to start and stop with Running, Off or Paused. |
Actions in every row:
- Open in browser: opens the container's web port while it runs.
- Open a terminal inside the container: a shell inside the container while it runs. Where it opens is set under Open with.
- More actions (…): Restart, Pause or Resume, and Delete.
Delete asks first ("Delete container"). A running container is stopped first, the image is kept.
How to do it
Stop and start a container
- Click the switch in the Status column of the container's row.
- The container stops, the switch shows Off.
- A second click starts it again.
Start a new container
Click Start container and fill in the dialog, see Start a container and Docker resources.
Free and Premium
The Docker tab is entirely part of Free. Containers do not count towards Free's six services.
Troubleshooting
| What you see | Why | What to do |
|---|---|---|
| "No Docker containers found." | The daemon runs but has no containers. | Create one with Start container. |
| "No Docker engine found. You can set one up in the Docker tab." | No engine is installed. | Install Docker Desktop, OrbStack or Colima. |
| "Could not start: …" | The engine could not be started. | Open the engine yourself, then click Check again. |
| A red message above the list | Docker refused an action. | Read the message, it is Docker's answer. |
See also
Container details and logs Free
Clicking a container in the Docker tab opens its details right below the row. You see how it was started, how much load it puts on the Mac right now, which ports, networks, mounts and environment variables it has, and you read its output.
Where to find it
Sites page, Docker tab, Containers sub-tab, click the name of a container. A second click closes the details. At the top of the details you choose between Details and Logs. WebDonkey remembers the choice until you quit the app.
Details
| Line | Content |
|---|---|
| ID | The container's ID. |
| Image | The image it runs from. |
| Created | When the container was created. |
| Restart policy | How Docker restarts it after it ends, such as no or unless-stopped. |
| Command | The command the container runs. |
| Usage | CPU, memory (RAM), network (NET) and disk (IO). |
| Ports | The port mappings. |
| Networks | The networks it is attached to. |
| Mounts | Mounted folders and volumes, one per line. |
| Environment | The environment variables, one per line. |
Lines without content are left out. The details refresh by themselves every ten seconds.
Logs
Shows the last lines of the container's output and reloads them every five seconds. At the top you choose 50, 200, 500 or 1000 lines, 200 by default. On the first load you briefly see the loading note, without output it says "No log output."
Troubleshooting
| What you see | Why | What to do |
|---|---|---|
| A red message instead of the details | Docker could not describe the container, for example because it was just deleted. | Refresh the list. |
| No Usage line | The container is not running. | Start it with its switch. |
See also
Start a container and Docker resources Free
Besides the containers, the Docker tab manages everything Docker builds containers from and works with: images, volumes, networks and Compose projects. This is also where you start a new container from an image and clean up what nobody needs any more.
Where to find it
Sites page, Docker tab. Start container is in the Containers sub-tab, the resources have sub-tabs of their own: Images, Volumes, Networks and Compose.
Start a container
Start container opens a dialog ("Starts a new container from an image."):
| Field | Meaning |
|---|---|
| Image | Required, such as nginx:alpine. If the image is not on the Mac, Docker pulls it. |
| Name (optional) | The container's name. Left empty, Docker assigns one. |
| Ports (one per line, host:container) | such as 8080:80. A port published like this is only reachable on this Mac (127.0.0.1). To open a port to the network, put the address in front: 0.0.0.0:8080:80. |
| Environment variables (one per line, KEY=value) | such as KEY=value. One line per variable, so values with commas stay intact. |
| Volumes (one per line, source:/target) | such as /host/path:/container/path. |
| Restart policy | no (default), always, unless-stopped or on-failure. |
Click Start container. The dialog closes and the container appears in the list.
Images
Above the table you see Total and In use, an input field with Pull, and the Clean up button.
- Pull fetches the image you entered, such as
nginx:alpine. - The columns: Image (name and tag), Size, Created and Status. The status shows in use when a container uses the image and unused for images without a name and tag.
- The trash icon deletes an image after a confirmation. Containers already running keep working. For images in use, the trash icon is locked.
- Clean up deletes every unused image. Images used by a container are kept.
Volumes
Volumes hold container data. Above the table you see Total, In use and Clean up.
- The columns: Volume (name and path), Driver, Size (when Docker knows it) and Used by with the names of the containers.
- The trash icon deletes a volume and all data in it after a confirmation. This cannot be undone. A volume in use cannot be deleted.
- Clean up deletes every volume no container uses, including the data in it.
Networks
Networks connect containers with each other. Above the table you see Total, In use and Clean up.
- The columns: Network, Driver and Container.
- Docker's own networks carry built-in and cannot be deleted.
- The trash icon deletes one of your own networks while no container is attached to it.
- Clean up deletes every network no container is attached to.
Compose
Shows the Compose projects on this machine, with Total and Running above them.
- The columns: Project (name and Compose file), Container (such as "2 of 3 running") and Status.
- The Status switch starts a project (
up) or stops its containers. - Show file opens the project's Compose file in a dialog.
- More actions (…): Restart and Shut down. Shutting down stops the project after a confirmation and removes its containers and networks. Named volumes are kept.
Clean up and Reclaimable
The top of the tab shows how much space can be freed (Reclaimable: …). Before every Clean up, WebDonkey asks and says what will be deleted. Docker's answer is shown above the list afterwards.
What happens in the background
WebDonkey calls the docker command for every action, such as docker image prune -f when cleaning up images. For images it never passes --all, so images with a name are kept even if no container uses them right now.
Troubleshooting
| What you see | Why | What to do |
|---|---|---|
| A red message after Pull | Docker does not know the image, or there is no network. | Check name and tag, such as nginx:alpine. |
| The trash icon is locked | The image, volume or network is still in use. | Delete the container that uses it first. |
| A port of the new container is not reachable from another device | WebDonkey binds ports without an address to 127.0.0.1. |
Put 0.0.0.0: in front of the port. |