Author: Stefan Kientzler
Updated on: 2023-05-18
Viewers: 684
Last month viewers: 41
Package: PHP Web Push Notifications Server
However, today's standard for live systems can become a problem during development in a closed or local network.
Read this tutorial to learn how the local development site can be available via the HTTPS protocol using the mkcert tool.
In this article you can read about the following:
- Why Can It Be Necessary to Use Locally-Trusted Certificates
- Configure your local Web Server for HTTPS Access
- Configure Clients in the Local Network to Access Server via HTTPS
- Additional Instructions to Install in Firefox/Edge/Opera
- Download and Install the PHP Web Push Notifications Server Package Using PHP Composer
Why Can It Be Necessary to Use Locally-Trusted Certificates
Since many browsers nowadays require a secure context to use some APIs (such as the Web push API, which is used by the PNServer packet), it is also necessary in the development environment that a secure connection via HTTPS is available.
But, normally, the Web server cannot be reached from outside within a development environment (regardless of whether it is a single workstation or a local network).
Thus there is no possibility for 'real' certification authorities (CAs) to verify a internal test-domain (i.E. 'mysite.dev', '127.0.0.1', localhost, ...).
This is where the 'mkcert' tool comes in! It is a simple, zero-config tool that creates and installs a local CA in the system root store, and generates locally-trusted certificates.
In view of the numerous web server systems that are used in the development, the tool cannot take care about the task of configuring the server to use the certificates. This article explains the configuration steps for an Apache web server.
Configure Your Local WebServer for HTTPS Access
The configuration on the web server takes place in three steps:
- Create and install the local CA on the system.
- Generate the locally trusted certificate(s) for the local Web site(s)
- Configure your Web server to use the certificate(s)
Create and Install the Local CA on the System
-
Download the latest pre-built binary according to your system.
-
Make the binary accessible from anywhere on your system:
- On a Linux machine (suggested path for Ubuntu - other distributions need other install command and may differ in the path):
Move the file to a system wide accessible directory (a directory contained in the system path - e.g./usr/local/bin
) and ensure it is executable:# first install certutil... sudo apt install libnss3-tools # move binary and make executable sudo mv mkcer-v1.x.x-linux-amd64 /usr/local/bin/mkcert sudo chmod +x /usr/local/bin/mkcert
- On a windows machine:
- Move the
mkcert-v1.x.x-windows-amd64.exe
to any decided folder and rename it tomkcert.exe
. - Add the folder to the system path.
- Move the
- On a Linux machine (suggested path for Ubuntu - other distributions need other install command and may differ in the path):
-
Create and install a local CA in the system root store:
mkcert -install
On windows there might popup a system message that ask if you realy want to install a certificate authority, that needs to be confirmed.
The command should return a message like:
Created a new local CA The local CA is now installed in the system trust store! The local CA is now installed in the Firefox and/or Chrome/Chromium trust store. Note: Firefox support is not available on your platform. (windows) (requires browser restart)!
The local CA is now installed on the system and the following two files have been generated:
rootCA.pem
rootCA-key.pem
These files are located in the directory ~/.local/share/mkcert
on Linux systems orUser/<username>/AppData/local/mkcert
on windows.
The rootCA.pem
is required if any client should get HTTPS access to this server!
Warning:
The rootCA-key.pem file that mkcert automatically generates gives complete power to intercept secure requests from your machine. !!! Do not share it !!!.
Generate the Locally Trusted Certificate(s) for the Local Website(s)
Next step is to create the certificate your Web server. If we assume an example system whose name is mysite.dev
, we can generate the trusted certification for it with the following command:
mkcert mysite.dev "*.mysite.dev" localhost 127.0.0.1
This creates the certificate for access via the server name mysite.dev
, via localhost
or the internal IP address:
Created a new certificate valid for the following names - "mysite.dev" - "*.mysite.dev" - "localhost" - "127.0.0.1"
The files mysite.dev+3.pem
and mysite.dev+3-key.pem
have been created in the current working directory.
If there are multiple virtual host configured on your server, just repeat the creation for each host:
E.g. mkcert virtualhost1
will create the files virtualhost1.pem
and virtualhost1-key.pem
.
Configuring the Web Server (Apache) to Use the Certificates
In view of the numerous web server systems that are used in the development, at this place i only describe the configuration for the (probably the most widespreaded) apache server.
To configure Apache to use these certificates, edit the default ssl configuration file (Linux: /etc/apache2/sites-available/default-ssl.conf
; Windows: <apache-path>\conf\extra\httpd-ssl.conf
) and change the SSL certificate and key file to point to the generated cert and key file. Following settings must be done:
SSLEngine on SSLCertificateFile <path-to-your-certificate>/mysite.dev+3.pem SSLCertificateKeyFile <path-to-your-certificate>/mysite.dev+3-key.pem
Linux
Enable the SSL module, enable the SSL site and restart the apache server:
sudo a2enmod ssl
sudo a2ensite default-ssl.conf
sudo systemctl restart apache2
For further virtual hosts, copy the associated conf file(s) (e.g. sudo cp virtualhost1.conf virtualhost1-ssl.conf
) and add the three lines from above with the corresponding certificate files. In addition, the port must be changed from :80 to :443:
<VirtualHost *:443>
Enable each site and restart the apache server.
Windows
Close the apache server, enable the required modules, include the SSL conf site and restart the apache server:
Edit the <apache-path>\conf\httpd.conf
and remove the comment-sign (#
) at following lines (if they have not already been removed so far...):
LoadModule log_config_module modules/mod_log_config.so LoadModule setenvif_module modules/mod_setenvif.so LoadModule ssl_module modules/mod_ssl.so LoadModule socache_shmcb_module modules/mod_socache_shmcb.so Include conf/extra/httpd-ssl.conf
Restart the httpd.exe.
Corresponding conf files must then be created and included in the httpd.conf
for further virtual hosts.
Configure Clients in the Local Network to Access the Server via HTTPS
If you are working in a local network and want to have HTTPS access to your development webserver, on each client the created CA from the server needs to be installed.
-
If not the same operating system is running on the client as on the server, the corresponding binary from the repository is required
-
Make the binary accessible from anywhere on your system.
-
Create any directory on the client to store the CA.
-
Copy the
rootCA.pem
file, that was created on your server to this directory.Note:
do NOT copy therootCA-key.pem
to any of the clients nor to any external target!! -
Set the environment variable CAROOT to this directory
- on Linux:
export CAROOT=<path-to-the-created-directory>
- on windows:
set CAROOT=<path-to-the-created-directory>
and verify the setting with
mkcert -CAROOT
- on Linux:
-
Call the installer
mkcert -install
You should get a messager like following:
The local CA is now installed in the system trust store! The local CA is now installed in the Firefox and/or Chrome/Chromium trust store (linux) Note: Firefox support is not available on your platform. (windows)
Additional instructions to install in Firefox/Edge/Opera
Add the Certificate to Other Browsers
Install the Certificate in Firefox on Windows
The current version of mkcert doesn't support the automatic installation for firefox on windwos. But don't worry, you can do this manually:
- Open the 'Preferences' in Firefox
- Type 'certificates' ('Zertifikate') into the search box on the top
- Click [View Certificates...], select the 'Authorities' ('Zertifizierungsstellen') Tab and click [Import...]
- Select the
rootCA.pem
file that have been created by the mkcert installer or that you have copied to your computer. - Close the window and restart Firefox
Install the Certificate in Edge on Windows
- Select 'Settings' from the 'Settings and more' menu.
- Go to the 'Privacy and Services' ('Datenschutz, Suche und Dienste') page and click on 'Manage Certificates' ('Zertifikate verwalten') in the 'Security' section to open the Certificates window.
- Navigate to the 'Trusted Root Certification Authorities' ('Vertrauenswürdige Stammzertifizierungsstellen') tab and click [Import...]
- Select the
rootCA.pem
file that have been created by the mkcert installer or that you have copied to your computer. - On the next page select 'Automatically Select the certificate...' ('Zertifikatsspeicher automatisch auswählen')
- If any further security warning dialog appears, click Yes
- Finish and relaunch the Browser.
Install the Certificate in Opera
- Type 'opera://settings/privacy' in the URL line
- Open the 'Security' pane and click 'Manage certificates'
- Navigate to the 'Trusted Root Certification Authorities' ('Vertrauenswürdige Stammzertifizierungsstellen') tab and click [Import...]
- Select the
rootCA.pem
file that have been created by the mkcert installer or that you have copied to your computer. - On the next page select 'Automatically Select the certificate...' ('Zertifikatsspeicher automatisch auswählen')
- If any further security warning dialog appears, click Yes
- Finish and relaunch the Browser.
Download and Install the PHP Web Push Notifications Server Package Using PHP Composer
This article is not so much about Web push notifications but setting SSL certificates to test those notifications from local development Web server environment is necessary to use the PHP Web Push Notifications Server package .
You can download or install this package using PHP Composer tool by going to this download page to get the package code.
You need to be a registered user or login to post a comment
Login Immediately with your account on:
Comments:
No comments were submitted yet.