Configuration
Free & PremiumThe Configuration page lets you edit the configuration files of your local setup without hunting for them in the sandbox: the php.ini of every PHP version, my.cnf, redis.conf, the web server files and more. It also covers files of your user account such as .zshrc or ssh/config, and any text file you add yourself. WebDonkey keeps the previous version on every save, so you can always go back.
What you do here
- Edit configuration files: change
php.ini,fpm.conf,my.cnfand the other files of your services, including the shared php.ini for all PHP versions. - System files and your own files: edit the shell, SSH, Git and package manager files of your account and add text files of your own to the list.
- Quick add value catalog: insert common settings with one click instead of looking up the spelling.
- Earlier versions and conflicts: compare and restore an older version, and what happens when someone changes the file at the same time.
Page layout
The page has three columns. Each one scrolls on its own, the page itself stays put.
| Area | Content |
|---|---|
| Left | The file list with three collapsible sections: Service configurations, Custom configurations and System files. Exactly one is open at a time. Clicking a heading opens that section and closes the other. |
| Middle | The editor with syntax highlighting. Its header shows the name and path of the file, Earlier versions and Save. After saving it shows saved · time. |
| Right | The Quick add catalog. It only appears for files that have one. |
Unsaved changes are not lost when you open another page in between. WebDonkey keeps them per file until you save or quit the app.
WebDonkey creates configuration files when they are missing and leaves your values alone afterwards. In a few files the app only maintains the lines that belong to the sandbox, such as the paths in my.cnf. The three main files of the web servers, on the other hand, are rewritten by WebDonkey on every start. They are read-only here, see Edit configuration files.
Free and Premium
Almost everything on this page is included in Free. Only the shared php.ini for all PHP versions (php (alle Versionen) · common.ini) is Premium to edit. On Free it carries the Premium badge in the list and opens read-only. The php.ini of each single PHP version stays editable on Free.
Edit configuration files Free & Premium
Service configurations lists the configuration files of the services WebDonkey runs for you. You change them in the app's editor and save with one click. For a change to take effect, restart the service afterwards. WebDonkey keeps the previous version before every save and refuses an fpm.conf that would stop PHP from starting.
Where to find it
Sidebar Local › Configuration. The Service configurations section on the left is open the first time, and the top file is selected. ⌘K finds the page with words like “php.ini” or “configuration”.
How to do it
- Click a file under Service configurations on the left, for example php 8.4.25 · php.ini.
- Change the text in the editor. The header shows the name and full path of the file.
- Click Save. The button is only active when your text differs from the saved one. Afterwards it says saved · time next to it.
- Restart the affected service so it reads the file again (see below).
If you need a setting whose exact spelling you don't remember, use the Quick add value catalog on the right.
Which files are listed
The shared php.ini always comes first, all other files follow in alphabetical order.
| Entry | What it is for |
|---|---|
| php (alle Versionen) · common.ini | Shared php.ini for every PHP version (Premium, see below) |
php <version> · php.ini |
The php.ini of an installed PHP version, one entry per version |
php <version> · fpm.conf |
The PHP-FPM settings of that version, such as the number of workers |
| mysql · my.cnf, mariadb · my.cnf | Server settings of MySQL and MariaDB |
| postgres · postgresql.conf | Server settings of PostgreSQL. The file lives in the PostgreSQL data directory |
| redis · redis.conf, memcached · memcached.args | Cache services |
| mongodb · mongod.conf | MongoDB |
| meilisearch · config.toml, opensearch · opensearch.yml, opensearch · jvm.options | Search services |
| minio · minio.env | MinIO (S3-compatible storage) |
| rabbitmq · rabbitmq.conf, rabbitmq · enabled_plugins | RabbitMQ |
| nginx · nginx.conf, apache · httpd.conf, caddy · Caddyfile | Main files of the web servers, read-only |
| nginx · custom.conf, apache · custom.conf, caddy · custom.caddy | Your own web server settings |
The list shows the files of every service WebDonkey knows, even if a service has never been started. For PHP, only installed versions appear. A file that does not exist yet carries the new badge. When you save it, WebDonkey creates it.
When a change takes effect
A service reads its configuration when it starts. Saving alone does not change the running service.
- PHP on the command line (terminal, Composer, scheduled tasks) reads php.ini on every call. The change applies right away.
- PHP for websites runs through PHP-FPM, which keeps its settings in memory. Restart the PHP service.
- Databases, web servers and all other services pick up the change after a restart.
You restart a single service on the Services page. Restart in the top bar stops all services and starts the ones that were active before again, handy after several changes at once.
Web servers: main file and your own file
WebDonkey rewrites nginx.conf, httpd.conf and the Caddyfile on every start, every reload and every site change. They hold the sandbox paths, the rules that allow access from this Mac only, and the default server that turns away foreign host names. A change there would be gone after the next start. So these files open read-only, with the note: “WebDonkey writes this file anew on every start, so it is read-only here.”
Each main file includes a file that WebDonkey creates once and never touches again. The button in the note takes you there, for example Open custom.conf.
| Web server | Your file | Where it applies |
|---|---|---|
| nginx | nginx · custom.conf | inside the http { } block, for all sites |
| Apache | apache · custom.conf | after the settings of httpd.conf |
| Caddy | caddy · custom.caddy | at the top level of the Caddyfile, for snippets and your own site blocks |
The shared php.ini
php (alle Versionen) · common.ini applies to every installed PHP version at once. WebDonkey loads it wherever it starts PHP: for websites through PHP-FPM, in the terminal and on the command line, in scheduled tasks and for Adminer. It is loaded after the php.ini of the version, so its values win. A memory_limit = 1024M here applies to PHP 8.3 and 8.4 alike, and you only enter it once.
On first start WebDonkey creates the file with a few commented-out examples (memory_limit, upload_max_filesize, post_max_size, max_execution_time, date.timezone). If you click one of these settings in Quick add, WebDonkey replaces the commented-out line with an active one.
What happens in the background
- The files live in WebDonkey's sandbox, by default under
~/Library/Application Support/WebDonkey/config/. Onlypostgresql.conflives in the PostgreSQL data directory. - Before saving, WebDonkey keeps the previous version in a folder of its own in the sandbox, never next to the file (see Earlier versions and conflicts).
- WebDonkey checks an
fpm.confwith PHP-FPM itself before saving. If the check fails, the old file stays unchanged. - WebDonkey maintains a few lines itself, your other values stay: it adds
curl.cainfoandopenssl.cafilefor the local certificate authority andsendmail_pathfor Mailpit tophp.inionce, if they are missing. Inmy.cnfit sets the paths to the data directory, socket, PID and log file on every start and adds a missingbind-address. - An
fpm.confwhoselisten =no longer matches the socket, or that contains php.ini directives such asmemory_limit, is rewritten by WebDonkey when that PHP version starts.
Free and Premium
Every file in this list is editable on Free except php (alle Versionen) · common.ini. On Free it carries the Premium badge, opens read-only, and Save stays off. You edit the php.ini of each single PHP version on Free as well.
Troubleshooting
| What you see | Why | What to do |
|---|---|---|
| Message “This php-fpm.conf was rejected and not saved” with an error text | PHP-FPM considers the file invalid, PHP would no longer start | Fix the line it names. Directives like memory_limit belong in php.ini, not in fpm.conf. |
| File opens read-only with a note pointing to another file | It is a main file of a web server | Open your own file with the button in the note and put your setting there. |
| common.ini cannot be saved | The shared php.ini is Premium | Put the value into the php.ini of the single PHP version, or activate Premium. |
| “The previous version could not be kept, so nothing was saved” | WebDonkey could not store the old version, for example because the disk is full | Free up space and save again. Your edit is still in the editor. |
| Dialog The file was changed in the meantime | The file was changed outside the editor since it was loaded | See Earlier versions and conflicts. |
| The change has no effect | The service still runs with the old configuration | Restart the service. |
See also
System files and your own files Free
Besides the files of your services, the Configuration page edits two more kinds of files. System files are the configuration files of your user account that you touch all the time as a developer: .zshrc, ssh/config, .gitconfig, .npmrc and the like. Under Custom configurations you add any text file from your Mac, such as a project's .env. Both open in the same editor, with saving, earlier versions and conflict protection.
Where to find it
Sidebar Local › Configuration, then the Custom configurations and System files sections on the left. Click a heading to open its section.
Edit system files
- Open System files on the left.
- Pick a file. Hovering over it shows the full path in the tooltip.
- Change the text and click Save.
The list is fixed and sorted into three groups:
| Group | Files |
|---|---|
| Shell | .zshrc, .zprofile, .zshenv, .bashrc, .bash_profile, .profile, .aliases, .inputrc |
| SSH & Git | ssh/config, ssh/known_hosts, .gitconfig, .gitignore_global |
| Web dev | .npmrc, .yarnrc, composer/config.json, .wgetrc, .curlrc, .editorconfig |
All of them live in your home folder, so ssh/config is ~/.ssh/config and composer/config.json is ~/.composer/config.json. A file that does not exist yet carries the new badge. When you save it, WebDonkey creates it. A change to a shell file applies to every terminal you open afterwards.
No other files can be edited under System files. WebDonkey checks on every read and save that the path really belongs to one of these entries, symbolic links included. /etc/hosts is deliberately not on the list: it belongs to the system, and WebDonkey maintains the entries for your sites there by itself.
Add custom configurations
- Open Custom configurations on the left.
- Click Add. The macOS file dialog opens, starting in your home folder.
- Pick the file. It appears in the list and opens in the editor right away.
While the list is empty, it says: “No files of your own yet. “Add” puts any text file from your Mac on this list.”
The file stays where it is. WebDonkey only remembers the path. If the path follows a symbolic link, WebDonkey resolves it once when you add the file and from then on always edits exactly that target.
Rename and remove
Hover over an entry and two icons appear on the right:
- Pencil (Rename (only in this list, the file keeps its name)): the name turns into a text field. Type your own name, up to 80 characters, and confirm with Enter or by leaving the field. Esc cancels. An empty field brings back the file name. Double-clicking the entry starts renaming as well.
- × (Remove from the list (the file itself stays)): WebDonkey asks Remove from the list?. Remove only drops the entry. The file itself stays on your Mac.
Limits for your own files
| What you see | Why |
|---|---|
| “Only files can be added, not folders.” | You picked a folder. |
| “This file is larger than 2 MB.” | Larger files are not configuration a text editor should load. |
| “This is not a text file (UTF-8).” | The file is binary or not saved as UTF-8. |
| “This file can't be read.” | You lack read permission. |
| The entry shows missing and cannot be clicked | The file was moved or deleted. Remove the entry and add the file again. |
| “You don't have write permission for this file, so it opens read-only.” | The file belongs to another user or is write-protected. You can read it but not save it. |
What happens in the background
- WebDonkey stores the list of your own files in its own database, not next to the files.
- Before every save, WebDonkey keeps the previous version, just like for service configurations (see Earlier versions and conflicts).
- System files and your own files have no Quick add catalog. The editor then takes the full width.
See also
Quick add value catalog Free
Next to the editor, many files get the Quick add catalog: common settings for exactly this file, with the right spelling, a sensible value for local development and a short description. One click inserts the line into your text. No more looking up whether it is upload_max_filesize or max_upload_size.
Where to find it
Sidebar Local › Configuration. Pick a file with a catalog under Service configurations, for example a php.ini. Quick add appears on the right.
How to do it
- Open the file, for example php 8.4.25 · php.ini.
- Type part of the name or description into Search values…, for example
upload. The search ignores case. - Click the entry. The line is in the editor and the entry gets a check mark.
- Adjust the value in the editor if you want a different one.
- Click Save and restart the service.
Each entry shows three lines: the name of the setting, the description (in English, as in the service's documentation) and the exact line that gets inserted.
Where the line goes
- If the setting is already in the file, WebDonkey replaces that line instead of adding a second one. This includes a commented-out line (with
;or#in front). So you activate an example with one click. - If it is not in the file yet, WebDonkey appends it at the end.
- The line is only in the editor at first. It is saved once you click Save.
What is in it
| File | Examples |
|---|---|
php.ini and common.ini |
memory_limit, upload_max_filesize, post_max_size, max_execution_time, max_input_vars, display_errors, error_reporting, date.timezone, OPcache, sessions, xdebug.mode, xdebug.start_with_request, xdebug.client_port |
fpm.conf |
pm.max_children, pm.start_servers, pm.max_requests, request_terminate_timeout |
my.cnf (MySQL, MariaDB) |
max_connections, max_allowed_packet, innodb_buffer_pool_size, sql_mode, slow query log, character set, group_concat_max_len |
postgresql.conf |
max_connections, shared_buffers, work_mem, log_min_duration_statement, timezone |
redis.conf |
maxmemory, maxmemory-policy, appendonly, requirepass |
opensearch.yml, jvm.options |
http.port, discovery.type, -Xms, -Xmx |
config.toml (Meilisearch) |
http_addr, env, master_key, memory and threads for indexing |
minio.env |
MINIO_ROOT_USER, MINIO_ROOT_PASSWORD, MINIO_BROWSER, MINIO_REGION |
memcached.args |
cache size, port, connections, maximum item size |
| nginx · custom.conf | client_max_body_size, fastcgi_read_timeout, buffers, timeouts, gzip |
| apache · custom.conf | Timeout, ProxyTimeout, KeepAlive, LimitRequestBody, ServerName, LogLevel |
For the Meilisearch master_key and the MinIO password, the catalog suggests a random value, not the same one on every Mac.
There is no catalog for mongod.conf (nested YAML, single lines would break the file), for custom.caddy, for the main files of the web servers, or for system and custom files. If the search finds nothing, it says No matching values.
See also
Earlier versions and conflicts Free
Every time you save, WebDonkey keeps the previous version of the file. Under Earlier versions you compare it with your current text and bring it back if needed. If someone changed the file while you had it open in the editor, WebDonkey asks before saving instead of overwriting their change. Both apply to every file on the page: service configurations, system files and your own files.
Where to find it
Sidebar Local › Configuration, pick a file, then Earlier versions at the top right of the editor.
Bring back an earlier version
- Open the file and click Earlier versions.
- The list on the left shows the kept versions with date, time and size, newest at the top. It is already selected.
- On the right you see the comparison: “Left: the earlier version. Right: the text in the editor.” Click another version on the left to compare it.
- Click Put into the editor. The dialog closes and the earlier version is in the editor.
- Click Save if you want to keep it. Only then does it become the file on disk again.
If there is no kept version yet, it says: “No earlier versions yet. WebDonkey keeps the previous version each time you save.”
What is kept
- WebDonkey keeps the last 5 versions of each file. Older ones are dropped.
- The versions live in a folder of their own in the sandbox (
config-history), never next to the file. That way no backup copy of a.envends up in a web folder where it could be served. - A file that did not exist before has no earlier version.
- If the previous version cannot be kept, WebDonkey does not save either. You then see “The previous version could not be kept, so nothing was saved” with the reason. Your text stays in the editor.
When the file was changed in the meantime
When you open a file, WebDonkey remembers which state of it you have in front of you. If the file was changed outside the editor since then, for example by an installer, another program or you in the terminal, saving brings up The file was changed in the meantime.
- Compare shows the file as it is on your Mac now on the left and your text on the right.
- Overwrite saves your text. WebDonkey keeps the version that is on disk right now first, you find it under Earlier versions.
- Reload discards your edits and loads the file from disk into the editor.
If you close the dialog without choosing, nothing happens. Your text stays in the editor and the file on disk is unchanged.