Installation Guide: MapServer on Ubuntu

Installation Guide: MapServer on Ubuntu (Oracle Cloud Free Tier)

Document Version: 1.0 Date: April 15, 2025

1. Introduction

1.1. Purpose This document provides step-by-step instructions for installing MapServer on an Ubuntu Linux server hosted within the Oracle Cloud Infrastructure (OCI) Free Tier. It focuses on using the Apache web server with the Common Gateway Interface (CGI) for handling MapServer requests.

1.2. Scope The guide covers system preparation, installation of Apache and MapServer packages using the Advanced Package Tool (APT), configuration of Apache for MapServer CGI execution, firewall adjustments within Oracle Cloud and Ubuntu, and basic testing procedures.

1.3. Target Audience & Prerequisites This guide assumes the user has:

An active Oracle Cloud Free Tier account.
An Ubuntu server instance (e.g., 20.04 LTS, 22.04 LTS) launched within OCI.
SSH access to the Ubuntu instance.
Basic familiarity with the Linux command line interface (CLI).

2. Phase 1: System Preparation & Apache Installation

2.1. Connect via SSH Establish an SSH connection to your Oracle Cloud Ubuntu instance using its public IP address.

Bash

ssh ubuntu@<your_server_public_ip>

(Replace <your_server_public_ip> with the actual public IP address)

2.2. Update System Packages Ensure your system’s package list and installed software are current.

Bash

sudo apt update
        sudo apt upgrade -y

2.3. Install Apache Web Server MapServer requires a web server; Apache is a common choice.

Bash

sudo apt install -y apache2

2.4. Verify Apache Installation Check if the Apache service is running correctly.

Bash

sudo systemctl status apache2

(Press q to exit the status view)

You should also be able to see the default Apache landing page by visiting http://<your_server_public_ip> in your web browser (firewall permitting - see Section 5).

3. Phase 2: MapServer Installation

3.1. Install Standard MapServer Packages via APT Install the MapServer CGI executable (cgi-mapserver), command-line utilities (mapserver-bin), and commonly used GDAL utilities (gdal-bin) from the standard Ubuntu repositories.

Bash

sudo apt install -y cgi-mapserver mapserver-bin gdal-bin

3.2. (Optional) Install Newer Versions via UbuntuGIS PPA To install more recent versions of MapServer and related geospatial libraries, you can optionally add and use the UbuntuGIS Personal Package Archive (PPA). Skip if standard versions are adequate.

Bash

# Add the PPA repository
        sudo add-apt-repository ppa:ubuntugis/ppa
        # Update package list after adding the PPA
        sudo apt update
        # Install the packages (will prefer PPA versions if available)
        sudo apt install -y cgi-mapserver mapserver-bin gdal-bin

3.3. Locate MapServer Executable (mapserv) Identify the installed location of the mapserv executable. This path is needed for Apache configuration.

Bash

which mapserv
        # Or check common locations like:
        ls -l /usr/lib/cgi-bin/mapserv

Make a note of the correct path (e.g., /usr/lib/cgi-bin/mapserv).

4. Phase 3: Apache Configuration for MapServer CGI

4.1. Enable Apache CGI Module Ensure the necessary Apache module for handling CGI scripts is enabled.

Bash

sudo a2enmod cgi

4.2. Create MapServer Apache Configuration File Create a dedicated configuration file for MapServer within Apache.

Bash

sudo nano /etc/apache2/conf-available/mapserver.conf

Paste the following configuration into the file. Verify the ScriptAlias path matches the location of mapserv found in step 3.3.

Apache

# MapServer Apache Configuration

        # Define an alias: requests to /cgi-bin/mapserv execute the mapserv program
        ScriptAlias /cgi-bin/mapserv /usr/lib/cgi-bin/mapserv

        # Configure the directory containing the mapserv executable
        <Directory /usr/lib/cgi-bin/>
            Options +ExecCGI -MultiViews +SymLinksIfOwnerMatch
            AllowOverride None
            Require all granted
        </Directory>

        # Optional: Set environment variables if needed (e.g., for PROJ data)
        # SetEnv PROJ_LIB /usr/share/proj/

Save the file (Ctrl+O, Enter in nano) and exit (Ctrl+X).

4.3. Enable MapServer Configuration Activate the newly created configuration file within Apache.

Bash

sudo a2enconf mapserver

4.4. Restart Apache Service Apply all configuration changes by restarting the Apache web server.

Bash

sudo systemctl restart apache2

5. Phase 4: Firewall Configuration

5.1. Oracle Cloud Infrastructure (OCI) Security List Configure the OCI firewall to allow incoming web traffic.

Log in to the OCI console.
Navigate: Networking -> Virtual Cloud Networks -> Your VCN -> Security Lists -> Your Subnet’s Security List (e.g., ‘Default Security List’).
Click ‘Add Ingress Rules’.
Add a rule with these settings:
- Source Type: CIDR
- Source CIDR: 0.0.0.0/0 (Allows traffic from any IP)
- IP Protocol: TCP
- Source Port Range: All
- Destination Port Range: 80 (for HTTP)
- (Optional) Add another rule for Destination Port 443 if planning HTTPS.
Click ‘Add Ingress Rules’ to save.

5.2. Ubuntu Firewall (UFW) Configure the local firewall on the Ubuntu server if it is active.

Check UFW status: sudo ufw status

If Status: active, allow Apache traffic:

Bash

sudo ufw allow 'Apache Full' # Allows HTTP & HTTPS
        # Or more specific rules:
        # sudo ufw allow 80/tcp      # HTTP only
        # sudo ufw allow 443/tcp     # HTTPS only
        sudo ufw reload

6. Phase 5: Testing the Installation

6.1. Basic MapServer CGI Test Verify that Apache can execute the mapserv program via the configured alias.

Open a web browser and navigate to: http://<your_server_public_ip>/cgi-bin/mapserv
Expected Result: A plain text message stating: No mapfile specified or mapfile not found. Seeing this message confirms successful execution. Errors like 404 (Not Found) or 403 (Forbidden) indicate problems with the Apache configuration (ScriptAlias, paths, permissions) or Apache restart.

6.2. Simple Mapfile Rendering Test (Recommended) Confirm MapServer can read a Mapfile and generate output.

Create a directory for mapfiles (e.g., /var/www/html/maps/). Ensure www-data user (Apache’s user) can read from it.

Create a basic Mapfile, for example /var/www/html/maps/test.map:

Code snippet

MAP
          NAME "TestMap"
          STATUS ON
          EXTENT -180 -90 180 90
          SIZE 400 200
          IMAGECOLOR 200 255 255 # Light blue background
        END

Adjust ownership/permissions if necessary: sudo chown www-data:www-data /var/www/html/maps/test.map
Test rendering via URL: http://<your_server_public_ip>/cgi-bin/mapserv?map=/var/www/html/maps/test.map&mode=map
Expected Result: A light blue rectangular image (400x200 pixels) displayed in the browser.

7. Important Considerations

Free Tier Performance: OCI Free Tier instances have limited CPU and RAM resources. Performance may be constrained for complex maps or significant user load.
Security: Review Apache directory permissions (Require all granted is permissive). Ensure the Apache user (www-data on Ubuntu) has appropriate read access to Mapfiles and data, but avoid overly broad permissions. Do not place sensitive configuration or data directly within the web server’s document root if possible.
Mapfiles and Data: This guide covers software installation. You are responsible for creating Mapfiles, preparing geographic data (Shapefiles, PostGIS, Rasters, etc.), and placing them on the server where MapServer can access them.
CGI vs. FastCGI: CGI is simpler to set up but less performant than FastCGI (mod_fcgid). Consider migrating to FastCGI for production or higher-load environments.
HTTPS/SSL: For any production use, configure HTTPS using SSL/TLS certificates (e.g., via Let’s Encrypt) to secure communication.

8. Conclusion

Following the steps outlined in this document should result in a functional MapServer installation accessible via Apache CGI on your Oracle Cloud Free Tier Ubuntu instance. Remember to consult the official MapServer documentation for advanced configuration and specific Mapfile directives.