Nginx: Difference between revisions

From Alpine Linux
(1. Added Dynamic Modules and Third-Party Support section; 2. Style/grammar amendments.)
 
(27 intermediate revisions by 9 users not shown)
Line 1: Line 1:
[https://nginx.org/en/ Nginx] (engine x) is an HTTP and reverse proxy server, a mail proxy server, and a generic TCP/UDP proxy server
[https://nginx.org/en/ Nginx] (engine x) is an HTTP and reverse proxy server, a mail proxy server, and a generic TCP/UDP proxy server.


== Installation ==
== Installation ==
Nginx package is available in the Alpine Linux repositories. To install it run:
The {{Pkg|nginx}} package is available in the Alpine Linux ''main'' repositories. To install it, run:


{{Cmd|apk add nginx}}
{{Cmd|$ doas apk update
$ doas apk add nginx}}


Creating new user and group 'www' for nginx
Create a new user and group 'www' for {{ic|nginx}}:
{{Cmd|adduser -D -u 1000 -g 'www' www}}
{{Cmd|$ doas adduser -D -g 'www' www}}


Create a directory for html files
Create a directory for html files:
{{Cmd|mkdir /www
{{Cmd|$ doas mkdir /www
chown -R www:www /var/lib/nginx
$ doas chown -R www:www /var/lib/nginx
chown -R www:www /www
$ doas chown -R www:www /www
}}
}}
== Dynamic Modules and Third-Party Support ==
Beginning in Alpine Linux 3.23 and in Edge, Nginx is compiled using {{ic|--with-compat}}.  This provides dynamic modules compatibility, making the building of third-party Nginx modules out-of-tree easier. Also, subpackage {{pkg|nginx-mod-dev}} supplies the required Nginx sources and build dependencies for building the modules.
{{Note|Nginx modules that are built against different versions/platforms – e.g. against other distributions or Alpine Linux branches – are not compatible and will fail. Use modules built only for the same Nginx version and for the same target platform.}}


== Configuration ==
== Configuration ==
You may want to make backup of original nginx.conf file before writting your own
You may want to make a backup of the original {{Path|nginx.conf}} file before writing your own:
{{Cmd|mv /etc/nginx/nginx.conf /etc/nginx/nginx.conf.orig}}
{{Cmd|$ doas mv /etc/nginx/nginx.conf /etc/nginx/nginx.conf.orig}}


Configuring Nginx to listen to port 80 and process .html or .htm files
Configure Nginx to listen to port 80 and to process .html or .htm files:
{{Cmd|vi /etc/nginx/nginx.conf}}
{{Cmd|$ doas vi /etc/nginx/nginx.conf}}
<pre>
<pre>
user                            www;
user                            www;
worker_processes                1;
worker_processes                auto; # it will be determinate automatically by the number of core


error_log                      /var/log/nginx/error.log warn;
error_log                      /var/log/nginx/error.log warn;
pid                            /var/run/nginx.pid;
#pid                            /var/run/nginx/nginx.pid; # it permit you to use rc-service nginx reload|restart|stop|start


events {
events {
Line 53: Line 59:


== Sample page ==
== Sample page ==
{{Cmd|vim /www/index.html}}
{{Cmd|$ doas vi /www/index.html}}
<pre>
<pre>
<!DOCTYPE html>
<!DOCTYPE html>
Line 68: Line 74:


== Controlling nginx ==
== Controlling nginx ==


=== Start Nginx ===
=== Start Nginx ===
After the installation Nginx is not running. To start Nginx, use ''start''.
After installation, Nginx is not yet running. To start Nginx, start the service:
{{Cmd|rc-service nginx start}}
{{Cmd|$ doas rc-service nginx start}}


You will get a feedback about the status.
You will get a feedback about the status.
<pre>
<pre>
* Caching service dependencies ...                    [ ok ]
  * /run/nginx: creating directory
  * /run/nginx: creating directory
  * /run/nginx: correcting owner                                                                                   [ ok ]
  * /run/nginx: correcting owner                        
  * Starting nginx ...                                                                                             [ ok ]
  * Starting nginx ...                                   [ ok ]
</pre>
 
=== Test configuration ===
Whenever one makes any changes to the Nginx configuration files, Nginx should first be checked for errors before restarting/reloading Nginx.<br>
The following will check for any duplicate configurations, syntax errors, etc. Run as user:
{{Cmd|$ nginx -t}}
 
You will get a feedback if it failed or not. If everything is fine, you will see the following and can then move ahead to reload the Nginx server.
<pre>
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful
</pre>
</pre>


=== Restart Nginx ===
=== Reload and Restart Nginx ===
After changing the configuration file nginx needs to be restarted.
Changes made in the configuration file will not be applied until the command to reload the configuration is sent to Nginx, or if it is restarted.
If you want to restart the web server use ''restart''.
''Reloading'' will do a "hot reload" of the configuration without server downtime. It will start the new worker processes with a new configuration and gracefully shutdown the old worker processes. If you have pending requests, then these will be handled by the old worker processes before it dies, so it is an extremely graceful way to reload the configuration. If you want to reload the web server, use ''reload'':
{{Cmd|rc-service nginx restart}}
{{Cmd|$ doas rc-service nginx reload}}
If you want to restart the web server, use ''restart'':
{{Cmd|$ doas rc-service nginx restart}}


=== Stop Nginx ===
=== Stop Nginx ===
If you want to stop the web server use ''stop''.
If you want to stop the web server, use ''stop'':
{{Cmd|rc-service nginx stop}}
{{Cmd|$ doas rc-service nginx stop}}


=== Runlevel ===
=== Runlevel ===
Normally you want to start the web server when the system is launching. This is done by adding nginx to the needed runlevel.
Normally, you would want to start the web server when the system is launching. This is done by adding Nginx to the needed runlevel:
{{Cmd|rc-update add nginx default}}
{{Cmd|$ doas rc-update add nginx default}}
 
Now, Nginx should start automatically whenever you next boot your machine. To test that, run:
{{cmd|$ doas reboot}}
 
To make sure that Nginx is started, run:
{{cmd|<nowiki>$ ps aux | grep nginx</nowiki>}}
 
You should get something like this:
<pre>
  263 root      0:00 nginx: master process /usr/sbin/nginx -c /etc/nginx/nginx.conf
  264 www        0:00 nginx: worker process
  310 root      0:00 grep nginx
</pre>


== Testing Nginx ==
== Testing Nginx ==
This section is assuming that nginx is running and sample html page "/www/index.html" is created. Launch a web browser and point it to your web server.
 
This section assumes that Nginx is running and that a sample html page ''/www/index.html'' is created. Launch a web browser and point it to your web server.
You should get:
You should get:
<pre>Server is online</pre>
<pre>Server is online</pre>


== Advanced configurations ==
== Troubleshooting ==
 
If Nginx is not started, check the Nginx log file:
{{cmd|$ doas less /var/log/nginx/error.log}}
 
Make sure that configuration file does not contain errors. Edit the file in case there are any:
{{cmd|$ nginx -t
$ doas vi /etc/nginx/nginx.conf}}
 
== Nginx with PHP ==


* [[Setting_Up_Nginx_with_PHP|Setting Up Nginx with PHP]]  
* [[Nginx_with_PHP#Configuration_of_PHP5|Setting Up Nginx with PHP5]] <br>
* [[Nginx_with_PHP#Configuration_of_PHP7|Setting Up Nginx with PHP7]] <br>
* [[Nginx_as_reverse_proxy_with_acme_(letsencrypt)|Setting Up Nginx as Reverse Proxy with acme (Let's Encrypt)]]


[[Category:Server]]
[[Category:Web Server]]

Latest revision as of 02:23, 1 January 2026

Nginx (engine x) is an HTTP and reverse proxy server, a mail proxy server, and a generic TCP/UDP proxy server.

Installation

The nginx package is available in the Alpine Linux main repositories. To install it, run:

$ doas apk update $ doas apk add nginx

Create a new user and group 'www' for nginx:

$ doas adduser -D -g 'www' www

Create a directory for html files:

$ doas mkdir /www $ doas chown -R www:www /var/lib/nginx $ doas chown -R www:www /www

Dynamic Modules and Third-Party Support

Beginning in Alpine Linux 3.23 and in Edge, Nginx is compiled using --with-compat. This provides dynamic modules compatibility, making the building of third-party Nginx modules out-of-tree easier. Also, subpackage nginx-mod-dev supplies the required Nginx sources and build dependencies for building the modules.

Note: Nginx modules that are built against different versions/platforms – e.g. against other distributions or Alpine Linux branches – are not compatible and will fail. Use modules built only for the same Nginx version and for the same target platform.

Configuration

You may want to make a backup of the original nginx.conf file before writing your own:

$ doas mv /etc/nginx/nginx.conf /etc/nginx/nginx.conf.orig

Configure Nginx to listen to port 80 and to process .html or .htm files:

$ doas vi /etc/nginx/nginx.conf

user                            www;
worker_processes                auto; # it will be determinate automatically by the number of core

error_log                       /var/log/nginx/error.log warn;
#pid                             /var/run/nginx/nginx.pid; # it permit you to use rc-service nginx reload|restart|stop|start

events {
    worker_connections          1024;
}

http {
    include                     /etc/nginx/mime.types;
    default_type                application/octet-stream;
    sendfile                    on;
    access_log                  /var/log/nginx/access.log;
    keepalive_timeout           3000;
    server {
        listen                  80;
        root                    /www;
        index                   index.html index.htm;
        server_name             localhost;
        client_max_body_size    32m;
        error_page              500 502 503 504  /50x.html;
        location = /50x.html {
              root              /var/lib/nginx/html;
        }
    }
}

Sample page

$ doas vi /www/index.html

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8" />
    <title>HTML5</title>
</head>
<body>
    Server is online
</body>
</html>

Controlling nginx

Start Nginx

After installation, Nginx is not yet running. To start Nginx, start the service:

$ doas rc-service nginx start

You will get a feedback about the status. 

 * Caching service dependencies ...                     [ ok ]
 * /run/nginx: creating directory
 * /run/nginx: correcting owner                         
 * Starting nginx ...                                   [ ok ]

Test configuration

Whenever one makes any changes to the Nginx configuration files, Nginx should first be checked for errors before restarting/reloading Nginx.
The following will check for any duplicate configurations, syntax errors, etc. Run as user:

$ nginx -t

You will get a feedback if it failed or not. If everything is fine, you will see the following and can then move ahead to reload the Nginx server. 

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

Reload and Restart Nginx

Changes made in the configuration file will not be applied until the command to reload the configuration is sent to Nginx, or if it is restarted. Reloading will do a "hot reload" of the configuration without server downtime. It will start the new worker processes with a new configuration and gracefully shutdown the old worker processes. If you have pending requests, then these will be handled by the old worker processes before it dies, so it is an extremely graceful way to reload the configuration. If you want to reload the web server, use reload:

$ doas rc-service nginx reload

If you want to restart the web server, use restart:

$ doas rc-service nginx restart

Stop Nginx

If you want to stop the web server, use stop:

$ doas rc-service nginx stop

Runlevel

Normally, you would want to start the web server when the system is launching. This is done by adding Nginx to the needed runlevel:

$ doas rc-update add nginx default

Now, Nginx should start automatically whenever you next boot your machine. To test that, run:

$ doas reboot

To make sure that Nginx is started, run:

$ ps aux | grep nginx

You should get something like this: 

  263 root       0:00 nginx: master process /usr/sbin/nginx -c /etc/nginx/nginx.conf
  264 www        0:00 nginx: worker process
  310 root       0:00 grep nginx

Testing Nginx

This section assumes that Nginx is running and that a sample html page /www/index.html is created. Launch a web browser and point it to your web server. You should get: 

Server is online

Troubleshooting

If Nginx is not started, check the Nginx log file:

$ doas less /var/log/nginx/error.log

Make sure that configuration file does not contain errors. Edit the file in case there are any:

$ nginx -t $ doas vi /etc/nginx/nginx.conf

Nginx with PHP

Retrieved from "https://wiki.alpinelinux.org/w/index.php?title=Nginx&oldid=31909"