Setting up a basic web server

Peter Boy (pboy) Version F40,F41 Last review: 2025-01-xx

The recommended and fully supported Fedora Web server is Apache, named httpd in the distribution. It is a Fedora Server key functionality that is part of the services specified in the technical specification. This article is about setting up a basic server. Further articles build on this and describe additional deployment configurations.

You are in the Fedora Server documentation staging area!

These documents are not approved yet and may be incomplete and/or incorrect. Take everything here with a grain of salt! You would probably prefer to study the published documentation.

Status of this document: Awaiting review (Jan 16, 2025).

The Fedora Web server httpd is an Apache web server. This document covers in detail especially the setup and maintenance of a basic Web service serving directly some html pages. A typical use scenario would be the Jamstack concept or a typical "one pager" more or less static web presentation (not to be confused with one page microservice application).

Additional articles describe how to use and further extend the configuration for other more complex usage scenarios, such as a frontend for application servers, a proxy for containers, the integration of dynamic languages, and other deployment options.

How it works

A Fedora Web Server installation stores the configuration in subdirectories of /etc/httpd. The directory /etc/httpd/conf.d is the more important one and stores especially the detailed and customized configuration options and supplements the generic configuration in /etc/httpd/conf/httpd.conf. The directory /etc/httpd/conf.modules.d contains the modules to be loaded dynamically and their configuration. Only very rarely something needs a change here.

The default data store is /var/www with the html-files in its subdirectory html. Additional directories are provided for extended configurations, e.g. the cgi-bin subdirectory for storing (classic) CGI files separately from document root.

This structure dates back to the early days of Linux systems, when the server hardware was capable to serve only one site (i.e. one Domain). As the hardware got more powerful, and became capable of serving more than one domain, "virtual hosts" were added that provided additional domains – distinguished either by name (virtual named hosts) or by IP. This situation is still virulent in the term "main“ site or "main“ server.

All these distinctions have now been abandoned. Today, it is widespread for a server to host several domains. And it is now best practice to configure everything as a virtual host, even if a server only serves one domain.

Following this evolution you need domain-specific subdirectories and therein additional appropriate subdirectories replacing the current outdated /var/www/[html|cgi-bin] structure of a Fedora default installation.

Additionally, in todays web world you would have many domains, which are served by one or more interdependant applications. A Web server is just one element of the software mix. According to the FHS, the /srv directory is the appropriate place for storing data. You create a domain-specific directory, e.g. example.com, and therein a htdocs subdirectory for the Web server, a webapps subdirectory for your web applicaion, e.g Ruby on Rails or Wildfly, a mail subdirectory for a postfix/dovecot mail hub, etc.

And there is yet another structural change. Every website now uses SSL/https as standard. It is no longer an add-on to the a standard http protocol, but an integral part of every website. Almost all browsers issue a serious warning when they come across an http page. This development is also not well supported by the current Fedora default installation.

In this guide, we will supplement and adjust the current standard httpd installation to take into account the outlined evolution and to create a solid foundation for a runtime environment that works as error-free as possible and makes the system administrator’s work easier. We are introducing additional subdirectories and changes to the default configuration files. Additionally, we are providing template files to make it easier to configure virtual hosts.

We describe a manual installation process and, as an alternative, an Ansible playbook to achieve the same result automatically.

Manual Installation

Prepare Storage

Set up one or more of the following alternatives.

Create a logical volume for /var/www either in the root volume group or in the user data volume group, depending on your system installation setup. We assume a volume of 5 GiB in the user data volume group here. Use either Cockpit or CLI

[…]$ sudo lvcreate -L 5G -n htdocs fedora_usrvg
[…]$ sudo mkfs.xfs /dev/fedora_usrvg/htdocs
[…]$ sudo mkdir /var/www
[…]$ sudo echo "UUID=$(blkid -s UUID -o value /dev/fedora_usrvg/htdocs) /var/www              auto    defaults    0 0"  >> /etc/fstab
[…]$ sudo mount -a
[…]$ sudo df -h
Filesystem                        Size  Used Avail Use% Mounted on
/dev/mapper/fedora_sysvg-root      12G  3.3G  8.0G  29% /
...
/dev/mapper/fedora_usrvg-htdocs   5.0G  130M  4.9G   3% /var/www

For the /var/www you may also decide for a thinly provisioned setup, instead. Create a thinly provisioned logical volume ˚htdocs˚ in a user data pool. Specify an initial maximum size based on current planning (can be increased later if necessary). Use either Cockpit or CLI

[…]# lvcreate --virtualsize 5G --thin fedora_usrvg/thinpool -n htdocs
  Logical volume "htdocs" created.
[…]# lvs
LV       VG           Attr       LSize    Pool     . . .
root     fedora_sysvg -wi-ao----  <11.18g
. . .
thinpool fedora_usrvg twi-aotz--  278.85g
htdocs   fedora_usrvg Vwi-a-tz--    5.00g thinpool  . . .

[…]# mkfs.xfs /dev/fedora_usrvg/htdocs
meta-data=/dev/fedora_usrvg/htdocs isize=512    agcount=8, agsize=163840 blks
         =                       sectsz=512   attr=2, projid32bit=1
...
         =                       sectsz=512   sunit=16 blks, lazy-count=1
realtime =none                   extsz=4096   blocks=0, rtextents=0
Discarding blocks...Done.

[…]# mkdir /var/www
[…]# echo "UUID=$(blkid -s UUID -o value /dev/fedora_usrvg/webconf) /var/www              auto    defaults    0 0"  >> /etc/fstab
[…]# mount -a
[…]# df -h
Filesystem                        Size  Used Avail Use% Mounted on
/dev/mapper/fedora_sysvg-root      12G  3.3G  8.0G  29% /
...
/dev/mapper/fedora_usrvg-htdocs   5.0G  130M  4.9G   3% /var/www

If not already done, create a logical volume for /srv either in the root volume group or in the user data volume group, depending on your system installation setup. We assume a volume of 50 GiB in the user data volume group here.

[…]$ sudo lvcreate -L 5G -n srv fedora_usrvg
[…]$ sudo mkfs.xfs -L srv /dev/mapper/fedora_usrvg-pgsql
[…]$ sudo echo "UUID=$(blkid -s UUID -o value /dev/mapper/fedora_usrvg-srv) /srv            xfs     defaults        0 0"  >> /etc/fstab
[…]$ sudo mount -a
[…]$ sudo df -h
Filesystem                        Size  Used Avail Use% Mounted on
/dev/mapper/fedora_sysvg-root    12G  3.3G  7.9G  30% /
...
/dev/mapper/fedora_usrvg-srv     50G  ...  ...   ...  /home

Install the httpd web server

[…]$ sudo dnf install httpd mod_ssl mod_md
[…]$ sudo firewall-cmd --add-service=https --permanent
[…]$ sudo firewall-cmd --add-service=http  --permanent
[…]$ sudo firewall-cmd --reload

Start the web server and check the status
```
[…]$ sudo systemctl start httpd
[…]$ sudo systemctl status httpd
```
The Web server should already answer to requests. Enter your server’s address into your browser’s address input field and Fedora test page should come up.

Figure 1. Fedora test page

This intermediate step is important as the server creates the default self-signed certificates.

If everything works as expected, activate the automatic server start at boot up.
```
[…]$ sudo systemctl enable httpd
Created symlink /etc/systemd/system/multi-user.target.wants/httpd.service → /usr/lib/systemd/system/httpd.service.
```

Optional: Prepare for different port assignments

If you intend to use httpd with different ports as 80 / 443 (e.g for a web application behind a reverse proxy) adjust the main config file and add a specific customize.conf file

Replace the main config file

[…]$ sudo mv /etc/httpd/conf/httpd.conf{,.f41}
[…]$ sudo wget https://hera.resdigita.eu/webservice-doc/conf/httpd.conf.mod -P /etc/httpd/conf/httpd.conf.mod
[…]$ sudo ln -s /etc/httpd/conf/httpd.conf.mod /etc/httpd/conf/httpd.conf

Add a specific customize.conf file

[…]$ sudo wget https://hera.resdigita.eu/webservice-doc/conf.d/customize.conf -P /etc/httpd/conf.d

Adjust the added customize.conf file according to your requirements. In any case you may specify a server name to avoid warning message at startup

[…]$ sudo vim /etc/httpd/conf.d/customize.conf
...
# Change this to Listen on a specific IP address, but note that if
# httpd.service is enabled to run at boot time, the address may not be
# available when the service starts.  See the httpd.service(8) man
# page for more information.
#
#Listen 12.34.56.78:80
Listen 80                          # <== Adjust if required

# ServerName gives the name and port that the server uses to identify itself.
# This can often be determined automatically, but we recommend you specify
# it explicitly to prevent problems during startup.
#
# If your host doesn't have a registered DNS name, enter its IP address here.
#
#ServerName www.example.com:80
ServerName myweb.mydomain.tld      # <== Add and Adjust anyway

Replace the ssl configuration file

[…]$ sudo mv /etc/httpd/conf.d/ssl.conf{,.f41}
[…]$ sudo wget https://hera.resdigita.eu/webservice-doc/conf.d/ssl.conf.f41-mod  -P /etc/httpd/conf.d
[…]$ sudo ln -s /etc/httpd/conf.d/ssl.conf.f41-mod /etc/httpd/conf.d/ssl.conf

Add a new configuration directory for vhost definitions

Create a new subdirectory for vhost configuration
```
[…]$ sudo mkdir  /etc/httpd/conf.vhosts.d
```

Integrate the directory into httpd configuration

[…]$ sudo wget https://hera.resdigita.eu/webservice-doc/conf.d/vhosts.conf  -P /etc/httpd/conf.d/

Add template file(s) to the conf.vhosts.d directory

[…]$ sudo wget https://hera.resdigita.eu/webservice-doc/conf.vhosts.d/vhost-starter-html.template  -P /etc/httpd/conf.vhost.d/
[…]$ sudo wget https://hera.resdigita.eu/webservice-doc/conf.vhosts.d/vhost-proxy-terminatessl-html.template  -P /etc/httpd/conf.vhost.d/
[…]$ sudo wget https://hera.resdigita.eu/webservice-doc/conf.vhosts.d/vhost-proxy-http-backend.template  -P /etc/httpd/conf.vhost.d/
[…]$ sudo wget https://hera.resdigita.eu/webservice-doc/conf.vhosts.d/vhost-proxy-ajp.template  -P /etc/httpd/conf.vhost.d/

Create a dedicated fallback default host configuration

The objective is to ensure that one of the dedicated websites does not inadvertently become the default page.
1. Copy the default vhost configuration file
  […]$ sudo wget https://hera.resdigita.eu/webservice-doc/conf.vhosts.d/aa_default.vhost -P /etc/httpd/conf.vhost.d/
2. If needed, adjust the default host configuration.
  
  This configuration uses the FQN hostname as ˚ServerName˚, as does Apache for the “main” configuration if you don’t explicitly set it.
  
  See the comments inside the config file.
  […]$ sudo vim /etc/httpd/conf.vhosts.d/aa_default.vhost
3. Create the root directory for the default host. Usually, this directory will be empty or nearly empty. So there is no need to care about a specific filesystem.
  […]$ sudo mkdir -p /[var/www|srv]/aa_default/htdocs
  If you want to publish extensive content at this address (the FQN hostname), skip this step and instead install a dedicated htdocs area, as described below in the section on setting up web sites.
  
  Leave the directory empty to trigger the default Fedora index page or you may create a custom index page.

Ansible assisted installation

coming soon (hopefully)

Manually setting up a basic web site

Ensure the necessary Domain Name entries are available
```
[…]$ sudo resolvectl query YOUR_DOMAIN_NAME(S)
```
Setup the web site Document Root directory

Create a subdirectory with an appropriate name in the specified directory position.It makes sense to follow a strict naming convention. We always use a short name here consisting of the domain name without the TLD part, i.e. “MY_DOMAIN” in the case of “MY_DOMA’IN.ORG”..
```
[…]$ sudo mkdir -p  /[var/www|srv]/SITE_SHORT_NAME/htdocs
```
If you use the /srv direcotry as a base, set the correct SELinux labels for htdocs.
```
[…]# semanage fcontext -a -t httpd_sys_content_t  -s system_u  "/srv/SITE_SHORT_NAME/htdocs(/.*)?"
[…]# restorecon -R -vF /srv/SITE_SHORT_NAME/htdocs
Relabeled /srv/SITE_SHORT_NAME/htdocs from unconfined_u:object_r:var_t:s0 to system_u:object_r:httpd_sys_content_t:s0
```
In the case of a large-scale web application such as Redmine or Wordpress, it may be useful to create a separate, thinly provisioned logical volume for the domain instead.

In any case, leave the document root (htdocs) empty for now.

Configure a Virtual Host for the domain

Copy the starter web site template
```
cp /etc/http/conf.vhost.d/vhost-starter-html.template /etc/http/conf.vhost.d/[SITE_SHOFRT_NAME].vhost
```
It is good practice to follow a systematic naming convention. Use the same as for the naming of the htdocs directories above.

Open the configuration file and adjust the placeholders.
Use the vim search and replace function to replace the placeholder at all the required locations in one go.

[…]$ sudo vi /etc/httpd/conf.vhost.d/[SITE_SHOFRT_NAME].vhost

# vhost-starter-html.template
...

#==> To adjust the template in vi/vim copy each line
# and replace the second part accordingly
# : %s/SHORT_DESCR/real_short_descr/g	e.g. my-domain.org production server
# : %s/FQN_NAME/your_domain/g			e.g. my-domain.org
# : %s/BASE_NAME/your_shortname/g		e.g. my-domain.org
# : %s/OPTIONAL_ALIAS/your_alias/g		e.g. www.my-domain.org
# afterwards delete these lines
...

Then browse through the file, check the settings according to the comments.

Restart and check the web server

[…]# systemctl  restart  httpd
[…]# systemctl  status  httpd
● httpd.service - The Apache HTTP Server
     Loaded: loaded (/usr/lib/systemd/system/httpd.service; enabled; preset: disabled)
     Active: active (running) since ...
  ...
  ...

Test the configuration

Again, enter your server’s address into your browser’s address input field. Because we already re-route everything to the secure site which uses a self-signed certificate so far, you get a warning message. Select "Advanced" and accept the 'risk' here. You’ll see the provisional test page.

Provide a SSL certificate

Use one of the alternatives as appropriate.

Using a Let’s Encrypt certificate by Apache md module

You have removed the “#” characters in front of the md configuration lines in the configuration file as described above. Otherwise, do so now and restart httpd.

Wait a few seconds to give the md module time to perform the necessary configuration steps in the background. Then trigger a graceful restart of httpd.
```
[…]# apachectl  graceful
```
The domain now has a certificate and can be accessed via SSL/https.

Use Let’s Encrypt certbot to generate a certificate

[…]$ sudo letsencrypt certonly --webroot  --webroot-path /var/www/[SITE_SHOFRT_NAME]/htdocs   --agree-tos --domains MY_DOMAIN.TLD[, OPTIONAL.MY_DOMAIN.TLD]   --renew-by-default   --email WEBMASTER@MY_DOMAIN.TLD

Open the vhost config file, comment out the selfsigned certificates, remove comment sign in front of Let’s Encrypt certifiates and adjust the certificate domains

[…]$ sudo vi /etc/httpd/conf.vhost.d/[SITE_SHOFRT_NAME].vhost

# vhost-starter-html.template
# ===============================================================
# Certificates configuration
# ===============================================================
SSLEngine on
# We rely on Fedora's systemwide configuration of SSL security.
...
# DEFAULT distribution provided, needed for initial startup.
#==> Comment OUT when module md created a certificate or you use custom
# certificates.
#SSLCertificateFile     /etc/pki/tls/certs/localhost.crt
#SSLCertificateKeyFile  /etc/pki/tls/private/localhost.key

# Letsencrypt certificates
# Preferably, the Apache md module should manage these (see above).
# Otherwise, insert certbot managed certificate configuration here.
SSLCertificateFile      /etc/letsencrypt/live/MY_DOMAIN.TLD/cert.pem
SSLCertificateKeyFile   /etc/letsencrypt/live/MY_DOMAIN.TLD/privkey.pem
SSLCertificateChainFile /etc/letsencrypt/live/MY_DOMAIN.TLD/chain.pem

Sometimes none of the described Let’s Encrypt generation methods works on aarch64 architecture. The Let’s Encrypt server does have permission to access your site. The issue is yet under investigation.

As a temporary workaround, stop the httpd server and use the standalone method to generate the certificates.

[…]$ sudo letsencrypt  certonly --standalone --preferred-challenges http -d MY_DOMAIN.TLD  --email WEBMASTER@MY_DOMAIN.TLD  --agree-tos

Modify the vhost file as described and restart the httpd server.

Configure access to your commercial certificates

Enter the storage addresses of your certificates in the appropriate place in the configuration file.

[…]$ sudo vi /etc/httpd/conf.vhost.d/[SITE_SHOFRT_NAME].vhost

# vhost-starter-html.template
...
 # ===============================================================
        # Certificates configuration
        # ===============================================================
        SSLEngine on
        # We rely on Fedora's systemwide configuration of SSL security.
...
# Custom certificates add here
#SSLCertificateFile      /etc/???    #<<= modify
#SSLCertificateKeyFile   /etc/???    #<<= modify
#SSLCertificateChainFile /etc/???    #<<= modify

Final commissioning

Copy your content into the htdocs subdirectory, add helper subdirectories as auth.d oder cgi-bin to the domain directory as appropriate.

Done.

Ansible assisted setting up a simple web site

coming soon (hopefully)

Want to help? Learn how to contribute to Fedora Docs ›