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: Work in progress (Jan 12, 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.

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.

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 of 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 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

  1. Prepare Storage

    Set up one or more of the following alternatives.

    1. 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. Use either Cockpit or CLI

      […]$ sudo TBD
      […]$ sudo TBD
    2. 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/webconf 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
    3. 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.

      […]$ sudo TBD
      […]$ sudo TBD
  2. 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
  3. 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.

    httpd basic setup 030
    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.
  4. Optional: 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

    1. 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  /etc/httpd/conf/httpd.conf.mod
      […]$ sudo ln -s /etc/httpd/conf/httpd.conf.mod /etc/httpd/conf/httpd.conf
    2. Add a specific customize.conf file

    3. 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
  5. 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
  6. Add a new configuration directory for vhost definitions

    1. Create a new subdirectory for vhost configuration

      […]$ sudo mkdir  /etc/httpd/conf.vhosts.d
    2. Integrate the directory into httpd configuration

      […]$ sudo wget https://hera.resdigita.eu/webservice-doc/conf.d/vhosts.conf  -P /etc/httpd/conf.d/
    3. Add template file(s) to the conf.vhosts.d directory

  7. Create a dedicated fallback default host configuration to ensure that one of the dedicated web sites does not become the default page accidentally.

    1. Copy the default vhost configuration file

    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.

      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.

      […]$ sudo mkdir -p /[var/www|srv]/aa_default/htdocs

Ansible assisted installation

(not) coming soon

Manually setting up a basic web site

  1. Ensure the necessary Domain Name entries are available

    […]$ sudo resolvectl query YOUR_DOMAIN_NAME(S)
  2. 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-domain.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 also be useful to create a separate, thinly provisioned logical volume for the domain.

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

  3. Configure a Virtual Host for the domain

    1. 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.

    2. Adjust the configuration file

      […]$ sudo vi /etc/httpd/conf.vhost.d/[SITE_SHOFRT_NAME].vhost
      
      # Apache vhost configuration for a static html server.
      # It manages SSL connections including certificates.
      # Initially, a self-signed certificate is active.
      # Incoming http traffic is automatically redirected to https.
      # Version 2.1
      
      #==> To adjust in vi/vim copy and adjust to the vi command line:
      # : %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
      # : %s/OPTIONAL_ALIAS/your_alias/g       e.g. www.my-domain.org
      # afterwards delete these lines
      
      # Certificates are managed by Apache md module.
      #==> To activate, remove the leading '#' character and comment out the
      # the default distribution provided certificates further down.
      #==> Adjust the mail address as appropriate!
      #MDContactEmail root@FQN_NAME
      #MDCertificateAgreement accepted
      #MDomain FQN_NAME
      
      <VirtualHost *:443>
      	# Secure virtual WEB host configuration for
      	# SHORT_DESCR
      
      	# The site can be accessed by https/ssl only. Without a valid certificate
      	# you have to use a self-signed certificate as a quick temporary fix.
      
      	ServerName      FQN_NAME
      	ServerAlias	OPTIONAL_ALIAS
      
          #==> Adjust the mail address as appropriate!
      	ServerAdmin     root@FQN_NAME
      
      	# ##########################################################################
      	# NOTE: We re-route everything from the insecure site to this secure site!
      	# ##########################################################################
      
      	# Optional: Ensure that all registered domain names are rewritten to the
      	# official base name
      	#RewriteEngine   On
      	#RewriteCond     %{HTTP_HOST}    !^FQN_NAME [NC]
      	#RewriteCond     %{HTTP_HOST}    !^$
      	#RewriteRule     ^(.*)$          https://FQN_NAME$1  [R=301,L]
      
      	# ====================================================================
      	# Certificates configuration
      	# ====================================================================
      	SSLEngine on
      	# We rely on Fedora's systemwide configuration of SSL security.
      
      	# By default, certificates are managed by Apache md module (see above)
      	# In this case, no certificates needs bo be configured here.
      	# Otherwise, insert proper certificate configuration.
      
      	# DEFAULT mod_ssl 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 managed by certbot (NOT by module md!)
      	#SSLCertificateFile      /etc/letsencrypt/live/DOMAIN_NAME/cert.pem
      	#SSLCertificateKeyFile   /etc/letsencrypt/live/DOMAIN_NAME/privkey.pem
      	#SSLCertificateChainFile /etc/letsencrypt/live/DOMAIN_NAME/chain.pem
      
      	# ===============================================================
      	# Directory Locations
      	# ===============================================================
      	DirectoryIndex	index.html
      	DocumentRoot	/srv/BASE_NAME/htdocs
      	# Specific to default 2.4 configuration:
      	# Enable access to server-specific base file location
      	<Directory "/srv/BASE_NAME">
      		AllowOverride None
      		# Allow open access:
      		Require all granted
      	</Directory>
      	# Further relax access to the default document root
      	<Directory "/srv/BASE_NAME/htdocs">
      		#
      		# Possible values for the Options directive are "None", "All",
      		# or any combination of:
      		#   Indexes Includes FollowSymLinks SymLinksifOwnerMatch ExecCGI MultiViews
      		#
      		# Note that "MultiViews" must be named *explicitly* --- "Options All"
      		# doesn't give it to you.
      		#
      		# The Options directive is both complicated and important.  Please see
      		# http://httpd.apache.org/docs/2.4/mod/core.html#options
      		# for more information.
      		#
      		Options Indexes FollowSymLinks
      
      		#
      		# AllowOverride controls what directives may be placed in .htaccess files.
      		# It can be "All", "None", or any combination of the keywords:
      		#   Options FileInfo AuthConfig Limit
      		#
      		AllowOverride None
      
      		#
      		# Controls who can get stuff from this server:
      		# Allow open access:
      		Require all granted
      
      	</Directory>
      
      	# ===============================================================
      	# Optional: Protect access to start page (and subsequent pages)
      	#==>        Ensure you created the additional auth.d directory
      	#           including SELinux labels
      	# ===============================================================
      	#<Location />
      	#	AuthType Basic
      	#	AuthName "Access start page"
      	#	AuthUserFile /srv/BASE_NAME/auth.d/htuser
      	#	Require valid-user
      	#</Location>
      
      	# ===============================================================
      	# Logging configuration
      	# ===============================================================
      	# Use separate log files for the SSL virtual host; note that LogLevel
      	# is not inherited from httpd.conf.
      	# NOTE: fail2ban searches for ~/logs/*access_log and  ~/logs/*error_log
      	#       to access log files to watch and analyze!
      	ErrorLog        logs/BASE_NAME-ssl_error_log
      	CustomLog       logs/BASE_NAME-ssl_access_log combined
      	LogLevel warn
      
      </VirtualHost>
      
      <VirtualHost *:80>
      	# INSECURE virtual WEB host configuration for
      	# SHORT_DESCR
      
      	# NOTE: Everything from the insecure port 80 is redirected to this instance'
      	#       SECURE site
      
      	ServerName      FQN_NAME
      	ServerAlias	OPTIONAL_ALIAS
      
      	ServerAdmin     root@FQN_NAME
      
      	# ##########################################################################
      	# NOTE: We re-route everything to the secure site!
      	#       We retain all aliase names for now.
      	#       There is no need for an exception for Let's Encrypt anymore.
      	#       Version 2.x can deal with self-signed certificates and https
      	# ##########################################################################
      	RewriteEngine   On
      	RewriteRule	(.*)	https://%{HTTP_HOST}%{REQUEST_URI} [R=301,L]
      
      	# ===============================================================
      	# Logging configuration
      	# ===============================================================
      	# Use separate log files for the SSL virtual host; note that LogLevel
      	# is not inherited from httpd.conf.
      	# NOTE: fail2ban searches for ~/logs/*access_log and  ~/logs/*error_log
      	#       to access log files to watch and analyze!
      	ErrorLog        logs/BASE_NAME-error_log
      	CustomLog       logs/BASE_NAME-access_log combined
      
      </VirtualHost>
  4. 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 ...
      ...
      ...
  5. 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.

  6. [ ] Final commissioning

    TBD

Ansible assisted setting up a simple web site

+ TBD