homebrew-malt

Malt Configuration Customization Guide

While Malt sets up your development environment based on malt.json, you can flexibly adapt it to project-specific requirements by customizing the generated configuration files. This guide explains how to customize settings, important notes, and provides specific examples.

Basic Customization Steps

Run malt create: First, execute the malt create command to generate the malt/ directory in your project root, along with conf, logs, tmp, var subdirectories, and configuration files for various services.
- About the public/ directory:
  - If a public/ directory does not exist in your project, malt create will create it and copy Malt’s basic dashboard files (index.html, index.php, etc.) into it. These files are for initial verification; feel free to edit or delete them and replace them with your project’s content.
  - If a public/ directory already exists in your project, malt create will not make any changes to this directory. Your existing files will be preserved and used as the web server’s document root.
Edit Configuration Files: To customize the behavior of services like web servers (Nginx, Apache), PHP, or MySQL, directly edit the configuration files generated within the malt/conf/ directory (e.g., nginx_80.conf, php.ini, my_3306.cnf).
Run malt start: After editing, run malt start to launch the services with your customized settings.

Important Notes:

Do Not Edit Template Files (share/templates/): These are internal templates used by Malt and should not be edited directly by the user. Always make customizations to the generated files within malt/conf/.
Re-running malt create:
- If the malt/ directory already exists, the malt create command will do nothing and exit. Existing configurations will not be overwritten.
- If you want to regenerate configuration files (e.g., after modifying malt.json), you must first manually delete (or rename) the existing malt/ directory, and then run malt create again.
- Preserving Customizations: Because re-running malt create requires deleting the malt/ directory, any customizations within malt/conf/ will be lost. It is highly recommended to place your malt/conf/ directory under version control (like Git) or back it up before re-running malt create if you want to preserve your changes.

Steps for Updating Environment After `malt.json` Changes

If you modify dependencies or ports in malt.json (e.g., removing Apache and adding Nginx), follow these steps to update your environment:

Update Dependencies: Run malt install to install any new dependencies. (You might need to manually run brew uninstall for dependencies that are no longer needed).
Remove Existing Configuration: Manually delete (or rename) the entire malt/ directory.
Regenerate Configuration Files: Run malt create to generate new configuration files in malt/conf/ based on the updated malt.json.
Re-apply Customizations (If Necessary): If you had previous customizations, re-apply them to the newly generated configuration files. (Version control can help you see the differences and re-apply changes).
Start Services: Run malt start.

Template Variables in Configuration Files

The configuration files generated by malt create in malt/conf/ utilize the following template variables, which are automatically expanded when services start. You can also use these variables in your customizations.

``: Absolute path to the project’s root directory (e.g., /Users/akihito/git/my-project). This is the directory containing malt.json.
``: Absolute path to the malt directory (e.g., /Users/akihito/git/my-project/malt).
``: Homebrew installation prefix (e.g., /opt/homebrew or /usr/local).
``: The PHP version specified in malt.json’s dependencies (e.g., 8.4).
``: (Within specific service config files) The port number that the configuration file pertains to.
``: (Within MySQL config files) A zero-based index when multiple ports are configured for the same service.
``: (Within php.ini) The extension=... or zend_extension=... lines generated based on malt.json’s php_extensions.
``: (Within nginx_main.conf) The include ...; lines for including the Nginx configuration files for each port (nginx_*.conf).
``: (Within Apache config files) The path to the Apache PHP module (libphp.so).

Specific Customization Examples

Here are some common customization examples. Edit the corresponding files within malt/conf/.

Nginx

Target files: malt/conf/nginx_*.conf, malt/conf/nginx_main.conf

Changing the Document Root: Malt assumes the document root is the public/ directory directly under your project root. If you want to change this, you need to manually edit the root directive in malt/conf/nginx_*.conf (and/or the DocumentRoot and <Directory> directives in malt/conf/httpd_*.conf) after running malt create.

# Example for Nginx (in malt/conf/nginx_*.conf)
server {
  listen ;
  server_name localhost;
  # root "/public"; # Original setting
  root "/path/to/your/webroot"; # Change to your desired path

  # ... other settings ...
}

# Example for Apache (in malt/conf/httpd_*.conf)
# DocumentRoot "/public" # Original setting
DocumentRoot "/path/to/your/webroot"
<Directory "/path/to/your/webroot"> # Also update the Directory path
  # ...
</Directory>

Using a Specific PHP Script as a Front Controller: For Single Page Applications (SPAs) or certain frameworks where you want all requests to go through a specific PHP script (other than index.php), modify try_files or fastcgi_param SCRIPT_FILENAME.

server {
  # ...
  location / {
    # try_files $uri /index.php?$query_string; # Common example
    try_files $uri /admin.php?$query_string; # Example using admin.php
  }

  location ~ \.php$ {
      include "/etc/nginx/fastcgi_params";
      fastcgi_pass 127.0.0.1:;
      fastcgi_index index.php;
      # fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; # Common example
      fastcgi_param SCRIPT_FILENAME /bootstrap/app.php; # Example specifying a specific script
      # ...
  }
  # ...
}

Note: These are just examples. Adjust them according to your framework or application requirements. You might need to change try_files, the SCRIPT_FILENAME in the location ~ \.php$ block, or both.

Adding Basic Authentication: To add Basic Auth to a specific path (e.g., /admin). First, create a password file using htpasswd.

# Example: Create a .htpasswd file in malt/conf/
htpasswd -c /conf/.htpasswd your_username

Then, add a location block to nginx_*.conf.

server {
  # ...
  location /admin {
    auth_basic "Restricted Area";
    auth_basic_user_file /conf/.htpasswd;

    # Add fastcgi_pass etc. for PHP if needed
    # try_files $uri /admin/index.php?$query_string;
    # location ~ \.php$ { ... }
  }
  # ...
}

PHP

Target files: malt/conf/php.ini, malt/conf/php-fpm_*.conf

Changing php.ini Settings: Modify memory limits, upload file sizes, error reporting levels, etc., by directly editing malt/conf/php.ini.

; memory_limit = 128M ; Original setting
memory_limit = 512M

; upload_max_filesize = 2M ; Original setting
upload_max_filesize = 100M
post_max_size = 100M ; Often set to match upload_max_filesize

; error_reporting = E_ALL & ~E_DEPRECATED & ~E_STRICT ; Example original setting
error_reporting = E_ALL ; Example: Show all errors during development

; display_errors = Off ; Example original setting
display_errors = On ; Example: Display errors on screen during development

Enabling/Configuring Xdebug (Example): If "xdebug" is included in malt.json’s php_extensions, zend_extension=xdebug.so is added to the end of malt/conf/php.ini. You can add more detailed settings.

[xdebug]
zend_extension=xdebug.so
xdebug.mode = debug,develop ; Adding 'develop' enhances var_dump output
xdebug.start_with_request = yes ; Always activate debugger on request
xdebug.client_host = 127.0.0.1
xdebug.client_port = 9003 ; Match your IDE's settings
; xdebug.log = /logs/xdebug.log ; Enable logging if needed

Adjusting PHP-FPM Process Count: For high-load development or testing, you can adjust process management settings in malt/conf/php-fpm_*.conf.

; pm = dynamic ; Example original setting
; pm.max_children = 5
; pm.start_servers = 2
; pm.min_spare_servers = 1
; pm.max_spare_servers = 3

; Example: Statically fix the number of processes (less recommended for dev)
; pm = static
; pm.max_children = 10

MySQL

Target file: malt/conf/my_*.cnf

Character Set Configuration: To change the default character set.

[mysqld]
# character-set-server = utf8mb4 ; Example original setting
# collation-server = utf8mb4_unicode_ci

[client]
# default-character-set = utf8mb4

Note: Changing character sets after a database already exists can affect existing data.

Adjusting Buffer Sizes, etc.: For performance tuning (usually unnecessary in a development environment).
```
[mysqld]
# key_buffer_size = 16M ; Example
# innodb_buffer_pool_size = 128M ; Example
```

(Examples for other services like Apache, Redis, etc., will be added later)

Language-Specific Guides

Malt primarily manages dependencies for background services (web servers, databases, caches) and development tools (wget, composer, etc.) via Homebrew. Version management for specific programming languages (e.g., switching between multiple Ruby versions) is typically handled by dedicated tools like rbenv, pyenv, nvm, volta, etc.

However, you can add language runtimes available via Homebrew (e.g., ruby@3.2, go, node) to Malt’s dependencies to install a specific version as a project dependency.

Here are examples of using Malt with different languages:

Ruby

Installation: Add "ruby@3.2" (or another available version) to dependencies in malt.json and run malt install.
Path Setup: The malt env command does not set the path for Ruby by default. To use the installed Ruby, either rely on Homebrew’s standard symlinks (e.g., /opt/homebrew/opt/ruby@3.2/bin) or use it in conjunction with a version manager like rbenv.
Malt Usage: Malt is useful for managing background services needed by Rails applications, such as MySQL, Redis, Memcached, etc.

Example malt.json (Rails):

{
  "project_name": "my_rails_app",
  "dependencies": [
    "ruby@3.2",
    "mysql@8.0",
    "redis",
    "imagemagick"
  ],
  "ports": {
    "mysql": [3306],
    "redis": [6379]
  }
}

Note: Including Ruby in dependencies is optional; you might not need it if using rbenv. The Rails server (Puma, Unicorn, etc.) is not started by malt start; start it normally (e.g., bin/rails server).

Go

Installation: Add "go" to dependencies in malt.json and run malt install.
Path Setup: malt env does not set the path for Go. Use the Go installation managed by Homebrew.
Malt Usage: While Go applications are often built as self-contained binaries, Malt can manage external services the application depends on, such as databases (MySQL) or caches (Redis).

Example malt.json (Go Web App):

{
  "project_name": "my_go_app",
  "dependencies": [
    "go",
    "mysql@8.0",
    "redis"
  ],
  "ports": {
    "mysql": [3306],
    "redis": [6379]
  }
}

Note: Start your Go application using go run main.go or by running the compiled binary directly.

Node.js

Installation: Add "node" to dependencies in malt.json and run malt install.
Path Setup: malt env does not set the path for Node.js. It’s common to use the Homebrew-installed Node.js or manage versions with tools like nvm or volta. If using nvm, etc., you might prefer not to include "node" in Malt’s dependencies.
Malt Usage: Manage databases (MySQL) or caches (Redis, Memcached) that your Node.js application relies on.

Example malt.json (Node.js App):

{
  "project_name": "my_node_app",
  "dependencies": [
    "mysql@8.0",
    "redis"
  ],
  "ports": {
    "mysql": [3306],
    "redis": [6379]
  }
}

Note: Including Node.js in dependencies is optional, especially if using nvm. Start your Node.js application using npm start, node server.js, etc.

Summary:

Malt is language-agnostic and helps define and manage dependencies for services and tools available via Homebrew on a per-project basis. While you can install language runtimes using Malt, combining it with dedicated language version managers is often effective.