Getting started
FreeWebDonkey is a local development environment for the Mac: web servers, PHP, Node.js, databases, a mailbox for test mail, HTTPS with its own certificate authority and many tools in one app. Everything WebDonkey installs and manages lives in a data folder of its own, the sandbox (~/Library/Application Support/WebDonkey). This chapter takes you from installing the app to your first site running in the browser.
What you do here
- Install: download the app, put it in Applications and start it.
- Setup on first launch: five short steps so domains work without a port and HTTPS without a warning.
- Your first site: enter a name, a domain and a folder, click Create, open it in the browser.
- First steps afterwards: finding your way around the window, search with ⌘K, the dashboard and notifications.
How it is organised
Getting started is not a page of its own in the app. It walks you through the setup dialog and the Sites page. How the window is laid out is covered in Window and navigation. The fastest way to work is shown in Search and commands.
Free and Premium
Everything in this chapter works on Free. Free has limits, for example at most three sites with SSL at the same time and at most six running services. Site packages (installing WordPress or Shopware right when you create a site, for example) are Premium. What belongs where is listed under Free and Premium.
Install Free
WebDonkey runs on macOS 11 or later. You download the app as a disk image (DMG), move it to the Applications folder and start it. On the first start a short dialog walks you through the setup.
How to do it
- Download WebDonkey from the download page: shop.webdonkey.io/download.
- Open the DMG and drag WebDonkey into the Applications folder.
- Start WebDonkey from Applications, not straight from the DMG.
- The window opens with the dialog Welcome to WebDonkey. What happens there is described in Setup on first launch.
On the first start WebDonkey picks the interface language from your Mac's language, English otherwise. You can change it at any time under Settings › General.
What happens in the background
- One data folder for everything. Installed versions, configurations, databases, logs and certificates live under
~/Library/Application Support/WebDonkey. You see the path and its size under Settings › System. - A few marked entries outside it. So domains and HTTPS work, WebDonkey writes entries to
/etc/hosts, DNS files for your domains, its certificate authority to your keychain and a marked block to~/.zshrc. The full list is shown by Remove WebDonkey from this Mac. - Homebrew for packages. WebDonkey installs PHP, databases and web servers through Homebrew when they are needed. If Homebrew is missing, the setup dialog installs it.
- The
wdcommand line. On every start WebDonkey places its bundledwdcommand in the folder it adds to your shell PATH for the terminal tools. You can use it in a new terminal, see CLI (wd). - Network. The app works locally. It goes online for package downloads, the update check, the license and content such as the changelog. Without a connection the app keeps working, only these requests wait.
Updates
WebDonkey finds new versions by itself and asks before it installs anything. The running version is shown at the top of the sidebar, a click on it opens the changelog. How the update check works is described in Updates.
Troubleshooting
| What you see | Why | What to do |
|---|---|---|
wd is not found in the terminal |
The terminal was already open, or Tools in the terminal is off | Open a new terminal and check Settings › Sites & services |
| The setup dialog is gone but steps are still open | You closed it with Do this later | It comes back on the next start, or you finish the steps in Settings, see Setup on first launch |
See also
Setup on first launch Free
On the first start WebDonkey opens the dialog Welcome to WebDonkey. In five steps it sets up what a local development environment on the Mac needs: Homebrew and nginx, entries in the hosts file, the front proxy on ports 80 and 443 and trust in its own certificate authority. The fifth step is optional. You can catch up on every step later in Settings.
Where to find it
The dialog appears by itself as long as the setup is not finished. If you close it with Do this later, with Esc or the cross, it comes back on the next start.
How to do it
- The five steps are shown as tiles at the top. A finished step carries a check mark.
- Read the text of the current step and click its button (the one with the lock icon).
- If macOS asks for your password or a confirmation, confirm. While it waits, the button reads Waiting for confirmation….
- Once the step is done, it says Already active.
- Next moves to the next step, Back to the previous one.
- On the last step Done finishes the setup. If required steps are still open, the button reads Finish anyway.
After Done or Finish anyway the dialog does not appear again.
The five steps
| Step | Button | What it does |
|---|---|---|
| Install Homebrew & nginx | Install Homebrew & nginx | Installs Homebrew with the official setup and then nginx. WebDonkey needs Homebrew to install PHP, databases and web servers, and nginx serves your sites. If both are present, there is nothing to do. macOS asks for your password once. You follow the progress live in a log box. |
| Allow writing to /etc/hosts | Grant access to hosts file | Adds the domains of your sites to /etc/hosts, so for example myproject.local points to your Mac (127.0.0.1). WebDonkey only touches its own marked lines. If the app cannot write the file directly, macOS asks for the administrator password. |
| Start front proxy on port 80 / 443 | Enable portmap | Starts the front proxy that binds ports 80 and 443. You then open sites without a port in the address. It runs under your user account, no admin password needed. |
| Trust the local root CA | Install CA | Creates a certificate authority (CA) of its own and adds it to your user's login keychain. https:// addresses of your sites then run without a browser warning. You can remove it at any time in Keychain Access. |
| Run on schedule without the app (optional) | Set up | Lets macOS run scheduled tasks and backups itself, even while WebDonkey is closed or nobody is logged in. macOS asks for the administrator password once. |
The last step shows a note: these runs use your user account, and folders such as Documents, Desktop, iCloud Drive or external drives need Full Disk Access for the WebDonkey runner, granted once in the macOS System Settings.
If nginx would upgrade Homebrew packages
If installing nginx would move Homebrew packages you already have to a newer version, the step lists them first (old and new version). The button then reads Upgrade and install and is your consent.
If ports 80 and 443 are taken
If another program holds the ports, the step names it and offers Free ports 80/443. A click quits that program and starts the front proxy. If it is the DDEV router, the button reads Move DDEV router: WebDonkey moves it to other ports (for example 9080/9443), running DDEV projects restart briefly and stay reachable.
What happens in the background
- Homebrew and nginx go where Homebrew normally installs them, not into the sandbox.
- The hosts entries carry a WebDonkey marker. Other lines stay untouched.
- The CA lives in the sandbox, the trust in it sits in the login keychain.
- For scheduling, WebDonkey registers one entry with macOS per scheduled task and per backup set.
Catching up in Settings
| Step | Where to catch up |
|---|---|
| Homebrew & nginx | on the Services page |
| Hosts file | Settings › Sites & services › Hosts file |
| Front proxy | Settings › Sites & services › Port forwarding 80 / 443 |
| Root CA | Settings › Sites & services › Local SSL root CA |
| Scheduling | Settings › System › Run on schedule without the app |
Without these steps your sites still run, but with a port in the address or a certificate warning in the browser.
Troubleshooting
| What you see | Why | What to do |
|---|---|---|
| This step did not work. with details to expand | A command failed, its message is in the details | Read the reason, fix it and click Retry |
| The button is unchanged after the password prompt | You cancelled the macOS password prompt | Nothing happened. Click again and confirm |
| The front proxy does not start | Another program holds port 80 or 443 | Free ports 80/443 or Move DDEV router |
See also
Your first site Free
A site is a local project with a domain of its own: a web server serves a folder on your Mac, with PHP or Node.js if you like, and with HTTPS. For your first site you need a project folder (or an empty one), an installed web server and a domain you make up.
Where to find it
- Click New site at the top of the window, or
- open Sites in the sidebar and create a new site there, or
- search for the action New site with ⌘K.
The New site view opens with numbered sections.
How to do it
- Under Site package (optional) keep No package selected if you bring your own project.
- Under Address enter a Name (anything you like, such as "My project") and a Domain, for example
myproject.local. You choose the ending freely; letters, digits or hyphens and an ending are required. - Under Folder & serving pick the Document root with Select: the folder the web server serves, often
public/inside your project. A path with~is stored as a full path. - Under Server & runtime choose the Web server and, if needed, a PHP version (optional) or Node version (optional).
- Leave SSL via local WebDonkey CA on if the site should run over
https://(on Free it starts off, see below). - Click Create at the bottom.
WebDonkey creates the site and starts right away what it needs: PHP-FPM, the web server and databases if required. The site then appears in the list of sites and opens in the browser.
Anything still missing is marked at its field and listed next to the button as Still needed: with the field names. Create stays disabled until name, domain, document root and web server are there.
Fields and options
| Field | Meaning |
|---|---|
| Site package (optional) | Installs a project along with the site, such as WordPress, Shopware or Laravel. Premium. No package creates an empty site for your own project. |
| Name | Display name in WebDonkey. |
| Domain | The address in the browser, for example myproject.local. |
| Aliases (optional, comma-separated) | More domains for the same site, such as www.myproject.local. |
| Document root | The folder the web server serves. |
| Project folder | Optional: where the code lives, if not in the document root. Folder, terminal and code editor open it. |
| Serve command | Leave empty for a normal site. Filled in (for example npm start), that process serves the site instead of a document root. The field Port then appears as well. |
| Web server | An installed web server with version and source. |
| PHP version (optional) | The PHP version of this site, (none) for plain HTML sites. |
| Node version (optional) | A Node version installed in WebDonkey. |
| SSL via local WebDonkey CA | Issues the site a certificate from the local CA. It runs without a browser warning once your Mac trusts the CA. |
Below the PHP version there is a note about the database host: in your site's code use 127.0.0.1 with port 3306 (MySQL) or 3307 (MariaDB), not localhost.
Everything about the fields, the site packages and editing a site is in Create and edit a site.
What happens in the background
- WebDonkey writes the web server configuration (vhost) and, with SSL, the certificate into the sandbox.
- The domain goes into
/etc/hostsand into the local name resolution. The very first time, macOS asks once for the administrator password, never again after that. - The site's services start right away. If they could not start, the site stays created but switched off, and WebDonkey tells you why.
Free and Premium
- On Free at most three sites have SSL at the same time. Next to the SSL box WebDonkey counts along (for example "1/3 sites with SSL"). If three other sites already have SSL, the box is locked.
- On Free, SSL starts off for a new site, on Premium it starts on.
- Site packages are Premium.
Troubleshooting
| What you see | Why | What to do |
|---|---|---|
| (none installed) at the web server | No web server is installed yet | Install nginx or Caddy under Services |
| Letters, digits and hyphens, with an ending, e.g. myproject.test below the domain | The domain has no ending or invalid characters | Enter a domain with an ending, such as myproject.local |
| A message that the site was created but its services did not start | A service is missing or a port is taken | Read the reason, fix it and switch the site on in the list or use Open in browser |
| The browser warns about the certificate | Your Mac does not trust the local CA yet | Trust CA under Settings › Sites & services |
| The address needs a port | The front proxy is not running | Enable under Port forwarding 80 / 443, see Sites & services |
If you close the form with input in it (✕, Esc, Cancel or Back to sites), WebDonkey asks Discard your input?. Keep editing takes you back, Discard closes.
See also
First steps afterwards Free
Your first site is running and the setup is done. This page shows you in a few minutes where things are and which moves you need every day.
Starting and stopping services
The top bar sits at the top of the window. On the left you find Start all, Stop all and Restart for all services at once, next to them New site. On the right the status shows how many services are running, for example "5/8 services running". A click on it opens Active services: there you stop or restart a single service without leaving the page.
Finding your way around
- The sidebar groups all pages by where the work happens: Local (on this Mac), Remote (on your servers), Monitoring, Tools and Account & Help.
- ⌘K opens Search and commands from anywhere. Pages, sites, services, settings and actions are in one list there. Type what you want to do, such as "certificate" or "php".
- The dashboard shows the state of services, sites and more at a glance. You can arrange it the way you like.
- The bell at the top of the sidebar collects what has finished: installs, backups, downloads, checks.
A few things to try
- Open a site in the browser: from the site's row under Sites or with ⌘K and the site's domain.
- Open the code: Open in editor on the site. Which editor opens is set under Open with.
- Test mail: WebDonkey catches the mail your projects send in a local mailbox. You see it under Mail.
- Get a second PHP version: under Services. Every site can have its own version.
- Change the look: with the theme switcher at the bottom of the sidebar.
- Add a keyboard shortcut: for an action you use often, see Keyboard shortcuts.
When something is off
At the bottom of the sidebar you find Report a problem. Use it to ask on Discord or report a fault in the shop, see Report a problem. Crashes and failed tasks show up under Logs.
Free and Premium
WebDonkey is fully usable on Free. Premium lifts the limits and unlocks areas that reach beyond this Mac, such as the remote pages for your servers. The overview is in Free and Premium.