Custom Configuration
Introduction #
Demyx Nginx is customized and works out of the box for your convenience, but sometimes (and maybe a lot of times) you will need to add some custom rules. Situations like a WordPress plugin that requires specific Nginx rules that needs to be added in order to function correctly, or you’re making a custom plugin but it also requires additional Nginx rules.
Structure #
Before we get into adding custom rules to Nginx, please familiarize yourself with the directory structure of Nginx within the container. This will be important on how to override certain rules. Below is an example of a typical directory structure for the Nginx’s container, located in /etc/demyx
.
$ demyx exec <app> -n tree -a /etc/demyx
/etc/demyx
├── conf.d
│ ├── security.conf
│ ├── static.conf
│ └── wp.conf
├── custom
├── extras
│ └── cf.conf
├── mime.types
└── nginx.conf
3 directories, 6 files
To get access inside the Nginx container, you can simply run the command demyx exec <app>
without any arguments to open an interactive bash shell.
Reference: demyx exec
Overrides #
Demyx Nginx was crafted to be “modularized” so you can easily customize it without worrying about losing your changes. The override files needs to follow the original directory and file structure in /etc/demyx/custom/nginx
. Below is a table of available files you can override. Please note that some files and/or directories will be missing depending on how you use Demyx and must be created when overriding.
Original | Override | Description |
---|---|---|
/etc/demyx/mime.types | /etc/demyx/custom/nginx/mime.types | Define file types for Nginx. |
/etc/demyx/conf.d/security.conf | /etc/demyx/custom/nginx/conf.d/security.conf | Basic security rules for WordPress or in general. |
/etc/demyx/conf.d/static.conf | /etc/demyx/custom/nginx/conf.d/static.conf | Add file types for Nginx to cache and others. |
/etc/demyx/conf.d/wp.conf | /etc/demyx/custom/nginx/conf.d/wp.conf | WordPress related rules. |
/etc/demyx/extras/auth.conf | /etc/demyx/custom/nginx/extras/auth.conf | Basic authentication. (Must be first activated in Demyx) |
/etc/demyx/extras/bedrock.conf | /etc/demyx/custom/nginx/extras/bedrock.conf | Bedrock (by roots.io) specific rules. (Must be first activated in Demyx) |
/etc/demyx/extras/cache-http.conf | /etc/demyx/custom/nginx/extras/cache-http.conf | Cache rules for the http block. (Must be first activated in Demyx) |
/etc/demyx/extras/cache-location.conf | /etc/demyx/custom/nginx/extras/cache-location.conf | Cache rules for the main PHP location block. (Must be first activated in Demyx) |
/etc/demyx/extras/cache-server.conf | /etc/demyx/custom/nginx/extras/cache-server.conf | Cache rules for the server block. (Must be first activated in Demyx) |
/etc/demyx/extras/rate-limit.conf | /etc/demyx/custom/nginx/extras/rate-limit.conf | Site-wide rate limit rules. (Must be first activated in Demyx) |
/etc/demyx/extras/server-00.conf | /etc/demyx/custom/nginx/extras/server-00.conf | Create this file for rules to show up in server block. |
/etc/demyx/extras/whitelist.conf | /etc/demyx/custom/nginx/extras/whitelist.conf | For IP based access. (Must be first activated in Demyx) |
Example #
Let’s override the wp.conf
file and modify one rule in there. We first need to check if you are running the latest version of Demyx and Demyx Nginx.
demyx pull demyx
– this example requires version1.7.x
or later.demyx pull nginx
– making sure the Demyx Nginx image is current.demyx host restart
– restarts the Demyx container and use the latest image.demyx compose <app> up -d
– recreates the app’s container and use the latest image.
Below is what you should see after running the commands above.
$ demyx version
1.7.0
$ demyx exec <app> -n ls /etc/demyx
conf.d custom extras mime.types nginx.conf
First, we need to create the necessary directories.
$ demyx exec <app> -n mkdir -p /etc/demyx/custom/nginx/conf.d
Copy the wp.conf
file.
$ demyx exec <app> -n cp /etc/demyx/conf.d/wp.conf /etc/demyx/custom/nginx/conf.d
For this example, we’re going to allow readme.html
to be accessible on the web.
$ demyx exec <app> -n "sed -i 's/readme|//g' /etc/demyx/custom/nginx/conf.d/wp.conf"
We’ll need to restart the Nginx container to apply the changes. Exit out of the container first by typing exit
.
$ demyx compose <app> -n restart
By default, any readme
files are denied but it should now be allowed. We can test for that by simply doing a curl
request or navigate to it on your browser.
# Before modifying the rules
$ curl -I http://<app>/readme.html
HTTP/1.1 403 Forbidden
Content-Length: 146
Content-Type: text/html
Date: Tue, 14 Nov 2023 04:03:25 GMT
Referrer-Policy: strict-origin-when-cross-origin
Server: nginx
X-Content-Type-Options: nosniff
X-Download-Options: noopen
X-Frame-Options: SAMEORIGIN
X-Xss-Protection: 1; mode=block
# After modifying the rules
$ curl -I http://<app>/readme.html
HTTP/1.1 200 OK
Accept-Ranges: bytes
Content-Length: 7399
Content-Type: text/html
Date: Tue, 14 Nov 2023 04:05:05 GMT
Etag: "6552f1f1-1ce7"
Last-Modified: Tue, 14 Nov 2023 04:05:05 GMT
Referrer-Policy: strict-origin-when-cross-origin
Server: nginx
X-Content-Type-Options: nosniff
X-Download-Options: noopen
X-Frame-Options: SAMEORIGIN
X-Powered-By: Demyx - https://demyx.sh
X-Xss-Protection: 1; mode=block
WordPress Example #
So now you’re probably wondering what about adding custom rules from a WordPress plugin? I will choose the Converter for Media – Optimize images | Convert WebP & AVIF plugin. From their documentation, we only have to do two steps. Once you install the plugin, you’ll see an error on the setting’s plugin page.
Let’s create the conf.d
directory, if you haven’t already, and the extras
directory. For this
$ demyx exec <app> -n mkdir -p /etc/demyx/custom/nginx/conf.d
$ demyx exec <app> -n mkdir -p /etc/demyx/custom/nginx/extras
We’ll need to copy and paste the following rules into the extras
directory.
# Create the file server-00.conf with the editor, this file will
# be included in the server block and before any location blocks
$ demyx exec <app> -n vi /etc/demyx/custom/nginx/extras/server-00.conf
# Copy the rules below
# Press i to enter insert mode and paste rules
# Press esc to exit out of insert mode
# Press shift + : to enter colon mode
# Type in wq and press enter to save
# BEGIN Converter for Media
set $ext_avif ".avif";
if ($http_accept !~* "image/avif") {
set $ext_avif "";
}
set $ext_webp ".webp";
if ($http_accept !~* "image/webp") {
set $ext_webp "";
}
location ~ /wp-content/(?<path>.+)\.(?<ext>jpe?g|png|gif|webp)$ {
add_header Vary Accept;
expires 365d;
try_files
/wp-content/uploads-webpc/$path.$ext$ext_avif
/wp-content/uploads-webpc/$path.$ext$ext_webp
$uri =404;
}
# END Converter for Media
Copy the original static.conf
file to the custom directory.
$ demyx exec <app> -n cp /etc/demyx/conf.d/static.conf /etc/demyx/custom/nginx/conf.d
Modify the regex in the location block using sed
to prevent caching of the following files: .jpg,.png,.gif,.webp
. According to the plugin documentation, caching these images aren’t necessary.
$ demyx exec <app> -n "sed -i -e 's/jpe?g|gif|//g' -e 's/png|//g' -e 's/|webp//g' /etc/demyx/custom/nginx/conf.d/static.conf"
Restart the app’s Nginx container.
$ demyx compose <app> -n restart
Go back to the plugin page, refresh your browser, and the error will be gone.
Conclusion #
Need further help or just want to hangout and chat, we have multiple channels for you to visit. To show support for this project, please consider buying coffee.
- Email – [email protected]
- Discussions – https://demyx.sh/discussions
Join us on Discord for latest news, faster support, or just chill.
Support this project by buying coffee (please).