If PHP is going to be used in Hugo, for example for a contact form, it is useful to use a local web server with PHP support for testing.
1. Choosing a local server
Local servers allow you to run your website without using hosting, right on your home computer. You can choose a local server depending on your needs, for example: Open Server Panel, MAMP, XAMPP, Denwer and WampServe.
1.1. Open Server Panel
Open Server Panel (OSPanel) is a portable software environment created specifically for web developers. The application runs on Windows OS, supports Apache and Nginx as a web server and provides the ability to run various versions of PHP, MySQL, PostgreSQL, MongoDB and other popular modules. OSPanel is a non-commercial project, distributed free of charge. You can download this program for Windows from the official website. Detailed documentation on installation and configuration is here.
1.1.1. Connecting Hugo to a local OSPanel server
Install OSPanel, for example, on the D: drive in the OSPanel folder.
OSPanel creates the following directory structure after installation:
. ├── addons # Add-ons
│ └── <add-on_name> # Add-on main directory
│ └── ospanel_data # Service files (settings and config sources)
├── bin # Common executable files
├── config # Settings
│ ├── <module_name> # Module settings
│ │ ├── default # Default profile directory
│ │ │ ├── templates # Configuration templates
│ │ │ └── settings.ini # Module settings for the Default profile
│ │ └── module.ini # Basic module settings (on/off + profile name)
│ ├── menu.ini # Menu settings
│ └── program.ini # Program settings
├── data # Data storage (databases, etc.)
├── home # User projects (domains)
├── licenses # Licenses for third-party components
├── logs # Log files
│ ├── domains # Project logs
│ └── mail # Mail storage
├── modules # Modules
│ └── <module_name> # Main module directory
│ └── ospanel_data # Service files (sources of settings and configs)
├── system # Service directory of the program
│ └── lang # Language files
├── temp # Temporary files
└── user # User data
└── ssl # User SSL files (keys, certificates, etc.)
First, create a subdirectory with the name of the new project in the home directory, for example: webpractica.
Next, in the root directory of the project, create subdirectories .osp and public.
Project settings are stored in the file .osp directory, create a project settings file project.ini with the following contents:
[domain_name]
php_engine = ...
public_dir = {base_dir}\public
Replace [domain_name] with the desired domain name of your project.
Specify the version of the PHP engine that you want to use to process PHP files of this domain in the php_engine parameter.
[!important] The value of
[domain_name]must match the domain name specified in the Hugo project settings fileconfig.toml, in thebaseURLline.
For example, if baseURL = "https://www.webpractica.ru/", the contents of the project.ini file should be:
[www.webpractica.ru]
php_engine = PHP-8.3
public_dir = {base_dir}\public
Below is the directory structure for our example.
D:
└── OSPanel
├── addons # Add-ons
│ └── <add-on_name> # Add-on main directory
│ └── ospanel_data # Service files (settings and config sources)
├── bin # Common executable files
├── config # Settings
│ ├── <module_name> # Module settings
│ │ ├── default # Default profile directory
│ │ │ ├── templates # Templates configurations
│ │ │ └── settings.ini # Module settings for the Default profile
│ │ └── module.ini # Basic module settings (on/off + profile name)
│ ├── menu.ini # Menu settings
│ └── program.ini # Program settings
├── data # Data storage (databases, etc.)
├── home # User projects (domains)
│ └── webpractica # Domain example
│ │ ├── .osp
│ │ │ └── project.ini # Project settings file
│ │ └── public # Directory for storing site folders and files generated by Hugo
├── licenses # Licenses for third-party components
├── logs # Log files
│ ├── domains # Project logs
│ └── mail # Mail storage
├── modules # Modules
│ └── <module_name> # Main module directory
│ └── ospanel_data # Service files (sources of settings and configs)
├── system # Service directory of the program
│ └── lang # Language files
├── temp # Temporary files
└── user # User data
└── ssl # User SSL files (keys, certificates, etc.)
1.1.2. Redirecting the public (Public) Hugo directory to the local server directory.
In order for Hugo to generate folders and site files in the directory we need, we need to specify the path in the publishDir parameter in the Hugo configuration file.
Below is the configuration in the config.toml file, for our example:
baseURL = "https://www.webpractica.ru/"
publishDir = "D:/OSPanel/home/webpractica/public"
Now, after executing the command hugo from the root of our Hugo project, the site folders and files will be generated in the directory of the custom domain OSPanel.
For our example, we will execute in the command line window (cmd):
d:
cd D:\Hugo\Sites\webpractica
hugo --gc --minify
1.2. MAMP
MAMP is a local server environment for web development with Apache, Nginx, PHP and MySQL for macOS and Windows, there is a paid and free solution.
1.2.1. Installing MAMP
Download MAMP from website and run the installation.
Local installation by default occurs in the Programs folder (the installation path can be changed).
The manufacturer confuses users in order to direct them to the paid version of MAMP Pro. In the Programs folder, there is only one icon for the MAMP Pro version. The MAMP.app application is hidden in the Programs/MAMP directory. However, there is also an icon for launching the MAMP version on the launcher. The icon has a gray background, unlike the MAMP Pro version with a turquoise background.
1.2.2. Configuring MAMP
The most important thing when configuring MAMP and connecting to Hugo is the root directory. It is configured in the settings in the Server section.
Clicking on the MAMP icon launches a minimal interface. Here you can set the web server - Apache or Nginx - and the PHP version. The gear in the upper left opens the settings dialog.
In the “Settings” - “General” section, you can enable “Start server”, “Check for updates” and “Stop server”. Disable “Cache”, and “Open WebStart page” is only necessary if, for example, you need phpMyAdmin a MySQL database. “WebStart” can also be launched from the application’s start page.
You can leave the ports unchanged. The Apache port is 8888, the Hugo project is called localhost:8888 in the browser.
In the “Settings” - “Server” - section, the root directory for Hugo web pages can be set using the “Select” mini-button. This is the most important setting. You can save your project locally, for example, in the directory /Users/myWeb/mamp-sites/mySite.
Settings - Cloud - the free version of MAMP does not have access to the cloud. If you select Cloud, you will be prompted to purchase a paid version.
1.2.3. Connecting Hugo to MAMP
Usually the contents of the public directory are copied to the root directory of the web server via sFTP. The Hugo project configuration file config.toml contains the baseurl domain name parameter.
For a local installation of MAMP, in config.toml you need to set: baseURL = "".
1.2.4. Redirecting the Hugo public directory to the local MAMP directory
The hugo terminal CLI command in the Hugo project directory creates a new static version of the Hugo website. By default, this data is available in the Hugo project/public directory. Now you can copy the contents of public to the MAMP root directory after each build. But this is very inconvenient.
You can edit and save your Hugo projects, for example, in Apple iCloud. This gives access to projects from all devices with iCloud access. With this approach, MAMP, of course, must be installed at the same path on all devices.
As described above, for example, the local root directory of the MAMP project is /Users/myWeb/mamp-sites/mySite. Now you need to make Hugo write files to this directory when creating a static version. To do this, insert the line publishDir = "/Users/myWeb/mamp-sites/mySite" into config.toml.
Below is an example of settings in config.toml:
# baseURL = "https://mySite.ru/"
baseURL = ""
publishDir = "/Users/myWeb/mamp-sites/mySite"
1.2.5. MAMP logs
If something doesn’t work, it can be useful to look at the MAMP logs. Apache, MySQL, and PHP logs are located in the Programs/MAMP/logs directory.
1.2.6. Removing MAMP
MAMP, as well as the installed MAMP Pro, can be completely removed from the Programs directory by deleting the Programs/MAMP directory and the “MAMP PRO.app” application from the Programs directory.
1.2.7. Conclusion
If you don’t need PHP for your site, the Hugo integrated IDE is quite sufficient. But if you need to use PHP for some dynamic things, MAMP is a free and working solution. Redirection with publishDir makes this very convenient.
[!WARNING] It is important that once the Hugo project is published, you must remember to set the
baseURLparameter back to the domain name. This should not be a problem, since you will not have to continue developing PHP code. At some point, this part will be finished, and you will no longer need to run MAMP. The Hugo IDE still serves everything underlocalhost:1313.