mirror of
https://github.com/jwinterm/modoboa.git
synced 2026-10-17 05:41:25 +02:00
356 lines
10 KiB
Markdown
356 lines
10 KiB
Markdown
---
|
||
title: manual step to install webserver component on modoboa
|
||
description: This guide describe how to install webserver on the modoboa platform
|
||
head:
|
||
- - meta
|
||
- name: 'keywords'
|
||
content: 'modoboa, installation, webserver, nginx, apache, wsgi'
|
||
---
|
||
|
||
# Web server {#webserver}
|
||
|
||
::: info
|
||
The following instructions are meant to help you get your site up and
|
||
running quickly. However it is not possible for the people contributing
|
||
documentation to Modoboa to test every single combination of web server,
|
||
wsgi server, distribution, etc. So it is possible that **your**
|
||
installation of uwsgi or nginx or Apache or what-have-you works
|
||
differently. Keep this in mind.
|
||
:::
|
||
|
||
## Apache2
|
||
|
||
First, make sure that `mod_wsgi` is installed on your server.
|
||
|
||
Create a new virtualhost in your Apache configuration and put the
|
||
following content inside:
|
||
|
||
```txt
|
||
WSGIPythonHome /var/www/modoboa/env
|
||
WSGIPythonPath /var/www/modoboa/instance
|
||
|
||
<VirtualHost *:80>
|
||
ServerName <your value>
|
||
|
||
DocumentRoot {{ modoboa_instance_path }}
|
||
|
||
Alias /media/ {{ modoboa_instance_path }}/media/
|
||
<Directory {{ modoboa_instance_path }}/media/>
|
||
Options FollowSymLinks
|
||
Require all granted
|
||
</Directory>
|
||
|
||
Alias /sitestatic/ {{ modoboa_instance_path }}/sitestatic/
|
||
<Directory {{ modoboa_instance_path }}/sitestatic/>
|
||
Options FollowSymLinks
|
||
Require all granted
|
||
</Directory>
|
||
|
||
WSGIScriptAliasMatch ^/(api|accounts) {{ modoboa_instance_path }}/instance/wsgi.py
|
||
WSGIApplicationGroup %{GLOBAL}
|
||
|
||
# Pass Authorization header to enable API usage:
|
||
WSGIPassAuthorization On
|
||
|
||
Alias / {{ modoboa_instance_path }}/frontend
|
||
<Directory {{ modoboa_instance_path }}/frontend>
|
||
Options FollowSymLinks
|
||
Require all granted
|
||
</Directory>
|
||
|
||
LogLevel info
|
||
</VirtualHost>
|
||
```
|
||
|
||
This is just one possible configuration.
|
||
|
||
Replace values between `<>` with yours. If you don't use a [virtualenv](http://virtualenv.readthedocs.org/en/latest/),
|
||
just remove the last part of the `WSGIDaemonProcess` directive. .. note:
|
||
|
||
You may need to add:
|
||
|
||
``` python [ {{ modoboa_instance_path }}/instance/wsgi.py]
|
||
import sys
|
||
|
||
sys.path.append('{{ modoboa_instance_path }}')
|
||
sys.path.append('{{ modoboa_venv_path }}/bin')
|
||
sys.path.append('{{ modoboa_venv_path }}/lib/python3.X/site-packages')
|
||
```
|
||
|
||
in :file:` {{ modoboa_instance_path }}/instance/wsgi.py`.
|
||
|
||
::: tip
|
||
You will certainly need more configuration in order to launch Apache.
|
||
:::
|
||
|
||
Now, you can go the `dovecot` section to continue the installation.
|
||
|
||
## Nginx
|
||
|
||
This section covers two different ways of running Modoboa behind
|
||
[Nginx](http://nginx.org/) using a WSGI application server.
|
||
|
||
Choose the one you prefer between
|
||
[Green Unicorn](http://gunicorn.org/) or [uWSGI](https://github.com/unbit/uwsgi).
|
||
|
||
In both cases, you\'ll need to download and [install nginx](http://wiki.nginx.org/Install).
|
||
|
||
### uWSGI
|
||
|
||
The following setup is meant to get you started quickly. You should read
|
||
the documentation of both nginx and uwsgi to understand how to optimize
|
||
their configuration for your site.
|
||
|
||
The Django documentation includes the following warning regarding uwsgi:
|
||
|
||
::: warning
|
||
Use uwsgi 1.2.6 or newer. If you do not, you *will* run into problems.
|
||
Modoboa will fail in obscure ways.
|
||
:::
|
||
|
||
To use this setup, first [download and install uwsgi](http://uwsgi-docs.readthedocs.org/en/latest/WSGIquickstart.html).
|
||
|
||
Recommend packages for debian and derivatives:
|
||
|
||
```shell
|
||
apt install uwsgi uwsgi-plugin-python3
|
||
```
|
||
|
||
Here is a sample nginx configuration:
|
||
|
||
``` nginx
|
||
upstream modoboa {
|
||
server unix:{{ uwsgi_socket_path }} fail_timeout=0;
|
||
}
|
||
|
||
server {
|
||
listen 80;
|
||
listen [::]:80;
|
||
server_name {{ hostname }};
|
||
rewrite ^ https://$server_name$request_uri? permanent;
|
||
}
|
||
|
||
server {
|
||
listen 443 ssl http2;
|
||
listen [::]:443 ssl http2;
|
||
server_name {{ hostname }};
|
||
root {{ modoboa_instance_path }};
|
||
|
||
ssl_certificate <ssl certificate for your site>;
|
||
ssl_certificate_key <ssl certificate key for your site>;
|
||
ssl_protocols TLSv1.2 TLSv1.3;
|
||
ssl_ciphers "ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-SHA384";
|
||
ssl_prefer_server_ciphers on;
|
||
ssl_session_cache shared:SSL:10m;
|
||
ssl_verify_depth 3;
|
||
ssl_dhparam /etc/nginx/dhparam.pem;
|
||
|
||
client_max_body_size 10M;
|
||
|
||
access_log /var/log/nginx/modoboa-access.log;
|
||
error_log /var/log/nginx/modoboa-error.log;
|
||
|
||
location /sitestatic/ {
|
||
try_files $uri $uri/ =404;
|
||
}
|
||
|
||
location /media/ {
|
||
try_files $uri $uri/ =404;
|
||
}
|
||
|
||
location ~ ^/(api|accounts|autodiscover) {
|
||
include uwsgi_params;
|
||
uwsgi_param UWSGI_SCRIPT instance.wsgi:application;
|
||
uwsgi_pass modoboa;
|
||
}
|
||
|
||
location / {
|
||
alias {{ modoboa_instance_path }}/frontend/;
|
||
index index.html;
|
||
|
||
expires -1;
|
||
add_header Pragma "no-cache";
|
||
add_header Cache-Control "no-store, no-cache, must-revalidate, post-check=0, pre-check=0";
|
||
|
||
try_files $uri $uri/ /index.html = 404;
|
||
}
|
||
}
|
||
```
|
||
|
||
'uwsgi_socket_path', `modoboa instance name`, `hostname`,
|
||
`modoboa_instance_path` and `ssl...` must be replaced by the value
|
||
you used when `you deployed your instance deployment`
|
||
|
||
In case you want to use enable auto-configuration functionality,
|
||
|
||
create a second virtualhost configuration the hostname should look like `autoconfig.your domain here`
|
||
|
||
```txt
|
||
server {
|
||
listen 80;
|
||
listen [::]:80;
|
||
server_name autoconfig.<your_domain>;
|
||
root {{ modoboa_instance_path }};
|
||
|
||
access_log /var/log/nginx/autoconfig-access.log;
|
||
error_log /var/log/nginx/autoconfig-error.log;
|
||
|
||
location ~ ^/(mail/config-v1.1.xml|mobileconfig) {
|
||
include uwsgi_params;
|
||
uwsgi_param UWSGI_SCRIPT instance.wsgi:application;
|
||
uwsgi_pass modoboa;
|
||
}
|
||
}
|
||
```
|
||
|
||
`{{ modoboa_instance_path }}` and `your_domain` must be replaced by the
|
||
value you used when `you deployed your instance <deployment>`{.interpreted-text role="ref"}.
|
||
|
||
If you do not plan to use SSL then change the listen directive to `listen 80;` and delete each of the following directives:
|
||
|
||
```txt
|
||
ssl on;
|
||
keepalive_timeout 70;
|
||
ssl_certificate {{ssl certificate for your site}};
|
||
ssl_certificate_key {{ssl certificate key for your site}};
|
||
uwsgi_param UWSGI_SCHEME https;
|
||
```
|
||
|
||
If you do plan to use SSL, you\'ll have to generate a certificate and a
|
||
key. [This article](http://wiki.nginx.org/HttpSslModule#Generate_Certificates)
|
||
contains information about how to do it.
|
||
|
||
Make sure to replace the `...` in the sample configuration with
|
||
appropriate values. Here are some explanations for the cases that may
|
||
not be completely self-explanatory:
|
||
|
||
* `hostname`: This is the URL which will be the root of your Modoboa site at your
|
||
domain. For instance, if your Modoboa installation is reachable at
|
||
at `https://foo/modoboa` then `hostname` is `/modoboa`. In this
|
||
case you probably also have to set the `alias` directives to point
|
||
to where Modoboa\'s sitestatic and media directories are because
|
||
otherwise nginx won\'t be able to find them.
|
||
|
||
If Modoboa is at the root of your domain, then `hostname` is an
|
||
empty string and can be deleted from the configuration above. In
|
||
this case, you probably do not need the `alias` directives.
|
||
* `uwsgi_socket_path`: The location where uwsig is listening. It could be a unix domain
|
||
socket or an address:port combination. Ubuntu configures uwsgi so that the port is:
|
||
```txt
|
||
unix:/run/uwsgi/app/ app name /socket
|
||
```
|
||
where `app name` is the name of the application.
|
||
|
||
Your uwsgi configuration should be:
|
||
|
||
``` ini{3,4}
|
||
[uwsgi]
|
||
# Not needed when using uwsgi from pip
|
||
# plugins = python
|
||
chdir = <modoboa_instance_path>
|
||
module = <name>.wsgi:application
|
||
master = true
|
||
harakiri = 60
|
||
processes = 4
|
||
vhost = true
|
||
no-default-app = true
|
||
buffer-size = 8192
|
||
max-requests = 5000
|
||
single-interpreter = true
|
||
```
|
||
|
||
The plugins directive should be turned on if you use a uwsgi
|
||
installation that requires it. If uwsgi was installed from pip, it does
|
||
not require it. In the configuration above:
|
||
|
||
* `modoboa_instance_path`: The directory where `manage.py` resides.
|
||
This directory is the parent of `modoboa's settings dir`
|
||
* `name`: The name that you passed to `modoboa-admin.py deploy`
|
||
when you created your Modoboa instance, usually `instance`.
|
||
|
||
Now, you can go the `dovecot` section to continue the installation.
|
||
|
||
### Green Unicorn
|
||
|
||
Firstly, [Download and install gunicorn](http://gunicorn.org/install.html).
|
||
|
||
Then, use the following sample gunicorn configuration
|
||
(create a new file named `gunicorn.conf.py` inside Modoboa's root dir):
|
||
|
||
```ini gunicorn.conf.py
|
||
backlog = 2048
|
||
bind = "unix:/var/run/gunicorn/modoboa.sock"
|
||
pidfile = "/var/run/gunicorn/modoboa.pid"
|
||
daemon = True
|
||
debug = False
|
||
workers = 2
|
||
logfile = "/var/log/gunicorn/modoboa.log"
|
||
loglevel = "info"
|
||
```
|
||
|
||
|
||
To start gunicorn, execute the following commands:
|
||
|
||
``` shell
|
||
$ cd {{ modoboa dir }}
|
||
$ gunicorn -c gunicorn.conf.py {{ APP/INSTANCE Name }}.wsgi:application
|
||
```
|
||
|
||
Now the nginx part. Just create a new virtual host and use the following
|
||
configuration:
|
||
|
||
``` nginx
|
||
upstream modoboa {
|
||
server unix:/var/run/gunicorn/modoboa.sock fail_timeout=0;
|
||
}
|
||
|
||
server {
|
||
listen 443 ssl;
|
||
ssl on;
|
||
keepalive_timeout 70;
|
||
|
||
server_name {{ host fqdn }};
|
||
root {{ modoboa_instance_path }};
|
||
|
||
access_log /var/log/nginx/{{ host fqdn }}.access.log;
|
||
error_log /var/log/nginx/{{ host fqdn }}.error.log;
|
||
|
||
ssl_certificate {{ ssl certificate for your site }};
|
||
ssl_certificate_key {{ ssl certificate key for your site }};
|
||
|
||
location /sitestatic/ {
|
||
autoindex on;
|
||
}
|
||
|
||
location /media/ {
|
||
autoindex on;
|
||
}
|
||
|
||
location / {
|
||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||
proxy_set_header Host $http_host;
|
||
proxy_redirect off;
|
||
proxy_set_header X-Forwarded-Protocol ssl;
|
||
proxy_pass http://modoboa;
|
||
}
|
||
}
|
||
```
|
||
|
||
If you do not plan to use SSL then change the listen directive to `listen 80;`
|
||
and delete each of the following directives:
|
||
|
||
```txt
|
||
ssl on;
|
||
keepalive_timeout 70;
|
||
ssl_certificate <ssl certificate for your site>;
|
||
ssl_certificate_key <ssl certificate key for your site>;
|
||
proxy_set_header X-Forwarded-Protocol ssl;
|
||
```
|
||
|
||
If you do plan to use SSL, you\'ll have to generate a certificate and a key.
|
||
|
||
[This article](http://wiki.nginx.org/HttpSslModule#Generate_Certificates) contains information about how to do it.
|
||
|
||
Paste this content to your configuration (replace values between `<>` with yours) and restart nginx.
|
||
|
||
Now, you can go the [Dovecot](./dovecot) section to continue the installation. |