diff --git a/workshop/content/docs/advanced/apache.md b/workshop/content/docs/advanced/apache.md index b05b627..88259c6 100644 --- a/workshop/content/docs/advanced/apache.md +++ b/workshop/content/docs/advanced/apache.md @@ -6,12 +6,12 @@ ## Overview -The Apache web server is used by the workshop Docker image. Since version 8.0 MapServer has a global config file. - At its heart MapServer is a command-line application that can be accessed through a web server. +The Apache web server is used by the workshop Docker image. + Apache has a [configuration file](https://github.com/MapServer/getting-started-with-mapserver/blob/main/docker/runtime/etc/apache2/conf-enabled/mapserver.conf). -The Docker image uses a [start-up script(https://github.com/MapServer/getting-started-with-mapserver/blob/main/docker/runtime/usr/local/bin/start-server). +The Docker image uses a [start-up script](https://github.com/MapServer/getting-started-with-mapserver/blob/main/docker/runtime/usr/local/bin/start-server). MapServer uses the [mod_fcgid module](https://httpd.apache.org/mod_fcgid/), which is an Apache module that provides FastCGI support. @@ -24,9 +24,9 @@ FcgidIdleTimeout ${IDLE_TIMEOUT} FcgidIOTimeout ${IO_TIMEOUT} ``` -These are all documented on the [reference page(https://httpd.apache.org/mod_fcgid/mod/mod_fcgid.html). +These are all documented on the [reference page](https://httpd.apache.org/mod_fcgid/mod/mod_fcgid.html). -These all have defaults in the Docker file, but can be overridden using environment variables. +These all have defaults in the Docker file, but can be overridden using Docker environment variables. ``` ENV MS_DEBUGLEVEL=0 \ diff --git a/workshop/content/docs/advanced/debugging.md b/workshop/content/docs/advanced/debugging.md index 2f4de3f..ef63e94 100644 --- a/workshop/content/docs/advanced/debugging.md +++ b/workshop/content/docs/advanced/debugging.md @@ -1,6 +1,8 @@ # Debugging MapServer -TODO +!!! warning + + This page is currently in a draft form. ```scala LAYER @@ -14,4 +16,6 @@ TODO Then follow live logs: -docker logs -f mapserver \ No newline at end of file +``` +docker logs -f mapserver +``` \ No newline at end of file diff --git a/workshop/content/docs/advanced/gdalg.md b/workshop/content/docs/advanced/gdalg.md index 6285087..7e1452d 100644 --- a/workshop/content/docs/advanced/gdalg.md +++ b/workshop/content/docs/advanced/gdalg.md @@ -15,6 +15,19 @@ MapServer reads a vector pipeline using the [GDALG: GDAL Streamed Algorithm](htt +The pipeline we will be running in this example reads a dataset from a FlatGeoBuf file, and applies +a buffer to it: + +
+ + +
+ + ## Checking the Pipelines with GDAL Before configuring MapServer, it is often easier to test your pipelines directly with GDAL, to ensure they run correctly. diff --git a/workshop/content/docs/credits.md b/workshop/content/docs/credits.md index 1f401fd..61c9aa1 100644 --- a/workshop/content/docs/credits.md +++ b/workshop/content/docs/credits.md @@ -4,12 +4,17 @@ title: Credits # Authors -- [Seth Girvin](https://geographika.net/) (found on GitHub at [@geographika](https://github.com/geographika)). Please get in touch if you'd like a particular topic added to the workshop, or require any MapServer development. +- [Seth Girvin](https://geographika.net/) (found on GitHub at [@geographika](https://github.com/geographika), + and Mastodon at [@geographika](https://mastodon.social/@geographika)). + Please get in touch if you'd like a particular topic added to the workshop, or require any MapServer development. # Thanks Thanks to the following for helping this workshop to be created and improved: +- The workshop participants at [FOSS4G Europe 2025](https://2025.europe.foss4g.org/) in Mostar, for their enthusiasm and feedback. +- [Even Rouault](https://www.osgeo.org/member/even-rouault/) and [Tom Kralidis](https://www.osgeo.org/member/tom-kralidis/) for + assisting, and valuable comments and additions at FOSS4G Europe 2025. - The workshop participants at [FOSS4G Europe 2024](https://2024.europe.foss4g.org/) for their participation, feedback, and for having everything installed ready for a 9am start! - [Michael Smith](https://www.osgeo.org/member/michael-smith/) for co-hosting the FOSS4G Europe 2024 workshop, and providing valuable tips and assistance. - Colleagues at [Compass Informatics](https://compass.ie/) for trialling the workshop and providing valuable feedback. diff --git a/workshop/content/docs/inputs/databases.md b/workshop/content/docs/inputs/databases.md index e5dce50..37cf5ca 100644 --- a/workshop/content/docs/inputs/databases.md +++ b/workshop/content/docs/inputs/databases.md @@ -6,12 +6,13 @@ MapServer can connect to most geospatial databases. There are native MapServer d [Oracle](https://mapserver.org/input/vector/oracle.html), and [Microsoft SQL Server](https://mapserver.org/input/vector/mssql.html). Other databases can be accessed through OGR, for example [MySQL](https://mapserver.org/input/vector/mysql.html). -In this exercise we'll be connecting to a PostGIS database to display water polygon features using a MapServer WMS. [PostGIS](https://postgis.net/) spatially enables the [PostgreSQL](https://www.postgresql.org/) -databases. +In this exercise we'll be connecting to a PostGIS database to display water polygon features using a MapServer WMS. +[PostGIS](https://postgis.net/) spatially enables [PostgreSQL](https://www.postgresql.org/) databases. + ## Docker Setup -To avoid having to install and setup a database we'll be using the [PostGIS Docker image](https://hub.docker.com/r/kartoza/postgis/) provided +To avoid having to install and set up a database we'll be using the [PostGIS Docker image](https://hub.docker.com/r/kartoza/postgis/) provided by [Kartoza](https://kartoza.com/). !!! info @@ -52,7 +53,7 @@ creating a new PostgreSQL connection: ## Adding Data to The Database -We can use the OGR tool [ogr2ogr](https://gdal.org/programs/ogr2ogr.html) installed on the MapServer container to add datasets to the PostgreSQL database. +We can use the GDAL CLI tool [gdal vector convert](https://gdal.org/en/stable/programs/gdal_vector_convert.html) installed on the MapServer container to add datasets to the PostgreSQL database. ```bash # connect to the MapServer Docker image which includes OGR tools for importing data @@ -95,10 +96,10 @@ Online example not available as no PostGIS installation on the server ## Exercises -1. Try and load another dataset into the database using the `ogr2ogr` approach above. +1. Try to load another dataset into the database using the `gdal vector convert` approach above. 2. Now add a new layer to the Mapfile to display the layer. You can make a direct request to MapServer in the form: . -3. Now update the JS file so the layer is visible as part of the interactive map, through WMS: +3. Now update the JS file so the layer is visible in the interactive map via WMS: ```js source: new ImageWMS({ diff --git a/workshop/content/docs/inputs/raster.md b/workshop/content/docs/inputs/raster.md index 3fdbfd6..40dde4d 100644 --- a/workshop/content/docs/inputs/raster.md +++ b/workshop/content/docs/inputs/raster.md @@ -3,9 +3,8 @@ ## Overview MapServer can serve both [vector](https://mapserver.org/input/vector/index.html) and [raster](https://mapserver.org/input/raster.html) data. - The dataset used in this example is elevation data from the [Estonian Geoportal](https://geoportaal.maaamet.ee/eng/Spatial-Data/Elevation-Data-p308.html), -and data provided by the Estonian Land Board 2024. It covers Tartu center and is from map sheet 474659. +provided by the Estonian Land Board (2024). It covers Tartu center and is from map sheet 474659.
@@ -47,7 +46,7 @@ LAYER END ``` -There are a few points to note in this Mapfile. +There are a few points to note about this Mapfile. ## Include Files @@ -80,7 +79,7 @@ END ## Composite Blocks -A [COMPOSITE](https://mapserver.org/mapfile/composite.html) block is used on the layer to make it 20% transparent. +A [COMPOSITE](https://mapserver.org/mapfile/composite.html) block is used to make the layer 20% transparent. ## Code diff --git a/workshop/content/docs/inputs/vector.md b/workshop/content/docs/inputs/vector.md index 92960b0..82daeaf 100644 --- a/workshop/content/docs/inputs/vector.md +++ b/workshop/content/docs/inputs/vector.md @@ -19,7 +19,7 @@ MapServer documentation. ## Remote Datasets using Virtual File Systems GDAL's [Virtual File Systems](https://gdal.org/user/virtual_file_systems.html) can be used to -access data over stored on a network, for example on a server or Amazon S3 bucket. +access data stored on a network, for example on a server or Amazon S3 bucket. ```scala CONNECTIONTYPE OGR @@ -75,7 +75,7 @@ than a huge GeoTIFF file. END ``` - In the `stars.js` you will need to ensure the `milkyway` layer is added to the OpenLayers map: + In the `stars.js` file you will need to ensure the `milkyway` layer is added to the OpenLayers map: ```js params: { 'LAYERS': 'constellations,stars,stars2,milkyway'}, diff --git a/workshop/content/docs/introduction/commandline.md b/workshop/content/docs/introduction/commandline.md index a58aeb0..b4b4e3d 100644 --- a/workshop/content/docs/introduction/commandline.md +++ b/workshop/content/docs/introduction/commandline.md @@ -19,7 +19,7 @@ INPUT=OGR INPUT=GDAL INPUT=SHAPEFILE INPUT=FLATGEOBUF ``` When run through a web server, data is passed to the `mapserv` application, which generates output that is then sent back through the web server. -All web requests can be recreated and tested on the command line, this makes it a handy debugging tool. +All web requests can be recreated and tested on the command line, making it a handy debugging tool. To test a URL such as run the following command: @@ -31,13 +31,13 @@ This will output a PNG image to the command line - this will look like garbage! We can save the output by redirecting it to a file using `>`. As the `mapserv` program returns responses for a web client it also returns HTTP headers. To create a valid image file we need to strip these -header by using the `-nh` (no headers) switch. +headers by using the `-nh` (no headers) switch. ```bash mapserv -nh "QUERY_STRING=map=/etc/mapserver/countries.map&mode=map" > /etc/mapserver/test.png ``` -`test.png` should now be on your local disk at `getting-started-with-mapserver/workshop/exercises/mapfiles`. +`test.png` should now be available on your local disk at `getting-started-with-mapserver/workshop/exercises/mapfiles`. ![Test output generated at the command line](../assets/images/command-line-test.png) @@ -45,7 +45,7 @@ mapserv -nh "QUERY_STRING=map=/etc/mapserver/countries.map&mode=map" > /etc/maps The `docker-compose.yml` file maps local folders to folders on the Docker container. Files created in the Docker container will be visible on your local disk, and files on your local disk will be visible in the container. - This is set in in the `volumes` section, using the syntax ` - LOCAL_FOLDER:CONTAINER_FOLDER` + This is set in the `volumes` section, using the syntax ` - LOCAL_FOLDER:CONTAINER_FOLDER` ```yaml volumes: diff --git a/workshop/content/docs/introduction/docker.md b/workshop/content/docs/introduction/docker.md index a6f00a2..1284cb8 100644 --- a/workshop/content/docs/introduction/docker.md +++ b/workshop/content/docs/introduction/docker.md @@ -6,12 +6,12 @@ We will be using MapServer on a Docker image for the workshop. This ensures that A custom MapServer Docker image has been created for the workshop, and the Dockerfile is found [here](https://github.com/MapServer/getting-started-with-mapserver/blob/main/docker/Dockerfile). -MapServer runs on the Apache web server - see the [Apache page](../advanced/apache.md) page for further details. +MapServer runs on the Apache web server - see the [Apache page](../advanced/apache.md) for further details. -It uses the Apache [mod_fcgid module](https://httpd.apache.org/mod_fcgid/), module that provides FastCGI support. +It uses the Apache [mod_fcgid module](https://httpd.apache.org/mod_fcgid/), a module that provides FastCGI support. MapServer runs on port `8080` on the Docker container, which is mapped to port `7000` on the local machine, as can be seen in the Docker compose file -located at `workshop\exercises\docker-compose.yml`: +located at `workshop/exercises/docker-compose.yml`: ```yaml mapserver: @@ -30,7 +30,7 @@ located at `workshop\exercises\docker-compose.yml`: ## JavaScript Application -A second container that serves the JavaScript example pages is also run using Docker. This uses Node and runs on port 7001 on both the container and the host machine. +A second Docker container serves the JavaScript example pages. This uses Node and runs on port 7001 on both the container and the host machine. ```yaml node: diff --git a/workshop/content/docs/introduction/introduction.md b/workshop/content/docs/introduction/introduction.md index 6cd4626..ba1e785 100644 --- a/workshop/content/docs/introduction/introduction.md +++ b/workshop/content/docs/introduction/introduction.md @@ -18,17 +18,17 @@ MapServer. Both vector data and raster data are covered. 4. MapServer **Outputs**. These exercises show how MapServer can publish data. When first created MapServer was used to produce map images, but now it can serve data out in -a large number of open geospatial formats. Focus is given to [OGC](https://www.ogc.org/standards/) +a large number of open geospatial formats. The focus is on [OGC](https://www.ogc.org/standards/) standards as these are free, open and interoperable. 5. **Advanced** topics. These are a collection of miscellaneous exercises that cover a wide range of MapServer functionality. Selected exercises will be chosen based on the -needs to the workshop participants. MapServer has over 25 years of development and +needs of the workshop participants. MapServer has over 25 years of development and features, so new topics will be added over time. ## Workshop Outline -Below is a rough timeline for how the timings of the 4-hour workshop, with a 15 minute break. +Below is a rough timeline for the 4-hour workshop, including a 15-minute break. These can be adapted based on the needs of the participants. - 0h00 - 0h30 - Introduction to the workshop, Docker setup and tests @@ -43,7 +43,7 @@ These can be adapted based on the needs of the participants. ## Test the Docker Compose config Before making any changes, we will make sure that the initial Docker Compose -setup provided to you is actually working. The configuration file for Docker Compose is found at the following location: +setup provided to you is actually working. The Docker Compose configuration file is located at: * `workshop/exercises/docker-compose.yml` @@ -59,9 +59,9 @@ setup provided to you is actually working. The configuration file for Docker Com 2. Open in your browser, you should see an error message! 3. Close by pressing `CTRL-C` -# Displaying your First Map +# Displaying Your First Map -- Ensure that you have MapServer setup and running at . +- Ensure that you have MapServer set up and running at . - Now try opening the following MapServer URL in your browser - diff --git a/workshop/content/docs/introduction/mapserver.md b/workshop/content/docs/introduction/mapserver.md index 8101476..26d8a77 100644 --- a/workshop/content/docs/introduction/mapserver.md +++ b/workshop/content/docs/introduction/mapserver.md @@ -24,7 +24,7 @@ In its most basic form, MapServer is a CGI program that sits inactive on your we A Mapfile is used to define the data contained in a map and how it will be displayed. -Mapfiles are text files, that contain hierarchical and nested blocks. An annotated Mapfile is displayed below: +Mapfiles are text files that contain hierarchical and nested blocks. An annotated Mapfile is displayed below: ``` scala --8<-- "countries.map" @@ -34,7 +34,7 @@ Mapfiles are text files, that contain hierarchical and nested blocks. An annotat ## MapServer development -The first release of MapServer was in 1997, and is written in a combination of C and C++. +The first release of MapServer was in 1997 and is written in a combination of C and C++. A summary of MapServer development from [OpenHub](https://openhub.net/p/MapServer) is shown below: @@ -43,7 +43,7 @@ A summary of MapServer development from [OpenHub](https://openhub.net/p/MapServe ## MapServer dependencies MapServer is built on several image rendering and geospatial C/C++ libraries. -The below image shows MapServer's key dependencies: +The image below shows MapServer's key dependencies: ![MapServer dependencies](../assets/images/mapserver-libs.png) @@ -52,4 +52,4 @@ This means that improvements and features in libraries like GDAL also become ava ## Interacting with MapServer Before services like WMS and WFS were added to MapServer, interaction was done using the custom keywords listed on the -[MapServer CGI Controls](https://mapserver.org/cgi/controls.html) page.These are still available for use in MapServer, but this workshop will focus on OGC services. For example we will use the [WMS](https://mapserver.org/ogc/wms_server.html) protocol to display the MapServer layer on top of an OSM background using OpenLayers. +[MapServer CGI Controls](https://mapserver.org/cgi/controls.html) page. These are still available for use in MapServer, but this workshop will focus on OGC services. For example we will use the [WMS](https://mapserver.org/ogc/wms_server.html) protocol to display the MapServer layer on top of an OSM background using OpenLayers. diff --git a/workshop/content/docs/introduction/openlayers.md b/workshop/content/docs/introduction/openlayers.md index 3c8bd36..63b949c 100644 --- a/workshop/content/docs/introduction/openlayers.md +++ b/workshop/content/docs/introduction/openlayers.md @@ -18,9 +18,10 @@ The HTML pages are served using a Docker container, and when the containers are running an index page for all workshop exercises is available at . The HTML files used in the workshop are located in `exercises/app`. -The JavaScript files can be found in `exercises/app/js`. These files can be edited, and changes viewed in the browser. +The JavaScript files can be found in `exercises/app/js`. These files can be edited and changes viewed in the browser. -To display MapServer WMS services we use an [ImageLayer](https://openlayers.org/en/latest/apidoc/module-ol_layer_Image-ImageLayer.html) with a [ImageWMS](https://openlayers.org/en/latest/apidoc/module-ol_source_ImageWMS-ImageWMS.html) source. +To display MapServer WMS services we use an [ImageLayer](https://openlayers.org/en/latest/apidoc/module-ol_layer_Image-ImageLayer.html) +with an [ImageWMS](https://openlayers.org/en/latest/apidoc/module-ol_source_ImageWMS-ImageWMS.html) source. These are created as follows: @@ -33,12 +34,12 @@ new ImageLayer({ }), ``` -The `LAYERS`parameter can be set to the Mapfile `MAP NAME` to show all layers, or you can add individual +The `LAYERS` parameter can be set to the Mapfile `MAP NAME` to show all layers, or you can add individual layers using a comma-separated list of `LAYER NAME`. ## WMS -We use the WMS protocol to serve out data. To configure this in our Mapfiles we need to include the following `WEB` block: +We use the WMS protocol to serve data. To configure this in our Mapfiles we need to include the following `WEB` block: ```scala WEB @@ -51,7 +52,7 @@ END ## Centres and Extents -In our OpenLayers maps we often want to set a starting extent or centre for the map. If our Mapfile contains an EXTENT in a different projection we can use the GDAL programs installed on the Docker image to convert coordinates to the OpenLayers projection: +In our OpenLayers maps we often want to set an initial extent or centre. If our Mapfile contains an `EXTENT` in a different projection we can use the GDAL programs installed on the Docker image to convert coordinates to the OpenLayers projection: ```bash diff --git a/workshop/content/docs/mapfile/labels.md b/workshop/content/docs/mapfile/labels.md index 9f44374..e118d8e 100644 --- a/workshop/content/docs/mapfile/labels.md +++ b/workshop/content/docs/mapfile/labels.md @@ -2,7 +2,7 @@ ## Overview -In this exercises we'll look at labelling features in a map. We'll be using a lakes dataset from the original Itasca County, Minnesota MapServer demo. +In this exercise we'll look at labelling features in a map. We'll be using a lakes dataset from the original Itasca County, Minnesota MapServer demo.
@@ -10,8 +10,8 @@ In this exercises we'll look at labelling features in a map. We'll be using a la ## Labels -[LABEL](https://mapserver.org/mapfile/label.html)s are placed within a `CLASS`. -Each class can label features differently. +[LABEL](https://mapserver.org/mapfile/label.html) elements are placed within a `CLASS`. +Each class can label features differently from others. Here is the `LABEL` block used in our example: @@ -31,7 +31,7 @@ END ## Label Positions -We use the [centerline](https://mapserver.org/mapfile/geomtransform.html#centerline) function as part of a [GEOMTRANSFORM](https://mapserver.org/mapfile/geomtransform.html) expression: +We use the [centerline](https://mapserver.org/mapfile/geomtransform.html#centerline) function within a [GEOMTRANSFORM](https://mapserver.org/mapfile/geomtransform.html) expression: ``` scala GEOMTRANSFORM (centerline(densify([shape], 0.1))) @@ -62,7 +62,7 @@ GEOMTRANSFORM (centerline(densify([shape], 0.1))) 1. Use a different font for the label by adding the following to the `LABEL` block: `FONT MonsieurLaDoulaise` and increasing the `SIZE` to `28`. The list of fonts available can be found in `workshop/exercises/mapfiles/data/fonts/fontset.txt`. 2. Comment out the `GEOMTRANSFORM (centerline([shape]))` and `ANGLE FOLLOW` lines (using `#`) to see its effect on the map. -3. If you have time, download a font you like from and unzip the .TTF file to `workshop/exercises/mapfiles/data/fonts/` +3. If you have time, download a font from and unzip the .TTF file to `workshop/exercises/mapfiles/data/fonts/` add a new entry to `fontset.txt` and use this font to draw your Map labels.