-
Notifications
You must be signed in to change notification settings - Fork 2
Expand file tree
/
Copy pathinstall.html
More file actions
920 lines (876 loc) · 65.8 KB
/
install.html
File metadata and controls
920 lines (876 loc) · 65.8 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
<!DOCTYPE html>
<html lang="en" data-content_root="../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Compilation & Installation — MapServer 8.6.3 documentation</title>
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=03e43079" />
<link rel="stylesheet" type="text/css" href="../_static/sphinx.css?v=48f05237" />
<link rel="stylesheet" type="text/css" href="../_static/copybutton.css?v=76b2166b" />
<link rel="stylesheet" type="text/css" href="../_static/sphinx_collapse.css?v=226d88b4" />
<link rel="stylesheet" type="text/css" href="../_static/custom.css?v=dd298242" />
<link rel="stylesheet" type="text/css" href="../_static/ribbon.css?v=ea091bf4" />
<script src="../_static/jquery.js?v=5d32c60e"></script>
<script src="../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
<script src="../_static/documentation_options.js?v=3e15dab7"></script>
<script src="../_static/doctools.js?v=fd6eb6e6"></script>
<script src="../_static/sphinx_highlight.js?v=6ffebe34"></script>
<script src="../_static/clipboard.min.js?v=a7894cd8"></script>
<script src="../_static/copybutton.js?v=f281be69"></script>
<link rel="icon" href="../_static/mapserver.ico"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Configuration File" href="config.html" />
<link rel="prev" title="MapCache 1.16.0" href="index.html" />
</head><body>
<!-- for main branch only, do not backport this -->
<table width="100%" style="width: 100%; background-color: white;">
<tr>
<td rowspan="2" style="padding: 10px 0px 10px 10px;">
<a href="../index.html" title="Home"><img src="../_static/banner.png" alt="MapServer banner" border="0" /></a>
</td>
<td style="padding: 10px 10px 0px 0px; text-align: right; vertical-align: top;">
<a href="../index.html" title="Home">Home</a> |
<a href="../products.html" title="Products (MapServer core, MapCache, TinyOWS">Products</a> |
<a href="https://github.com/MapServer/MapServer/issues/" title="Issue Tracker (MapServer core)">Issue Tracker</a> |
<a href="../community/service_providers.html" title="Professional Service Providers">Service Providers</a> |
<a href="../faq.html" title="Frequently Asked Questions">FAQ</a> |
<a href="https://fosstodon.org/@mapserver" title="Mastodon" target="_blank">Mastodon</a> |
<a href="../download.html" title="Download Source or Binaries">Download </a> |
<a class="badge" href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=KRJ2X44N3HA6U&source=url" target="_blank">
<img src="https://img.shields.io/badge/donate-%E2%9D%A4%C2%A0-ff69b4.svg?style=flat" alt="Donate to MapServer">
</a>
</td>
</tr>
<tr>
<td style="padding: 0px 10px 0px 0px; text-align: right; vertical-align: bottom;">
<img src="../_static/flagicons/en.png" alt="en" title="en" border="0" width="18px" height="13px"/>
<a href="../ar/mapcache/install.html"><img src="../_static/flagicons/ar.png" alt="ar" title="ar" border="0" /></a>
<a href="../de/mapcache/install.html"><img src="../_static/flagicons/de.png" alt="de" title="de" border="0" /></a>
<a href="../el/mapcache/install.html"><img src="../_static/flagicons/el.png" alt="el" title="el" border="0" /></a>
<a href="../es/mapcache/install.html"><img src="../_static/flagicons/es.png" alt="es" title="es" border="0" /></a>
<a href="../fr/mapcache/install.html"><img src="../_static/flagicons/fr.png" alt="fr" title="fr" border="0" /></a>
<a href="../id/mapcache/install.html"><img src="../_static/flagicons/id.png" alt="id" title="id" border="0" /></a>
<a href="../it/mapcache/install.html"><img src="../_static/flagicons/it.png" alt="it" title="it" border="0" /></a>
<a href="../ja/mapcache/install.html"><img src="../_static/flagicons/ja.png" alt="ja" title="ja" border="0" /></a>
<a href="../nl_NL/mapcache/install.html"><img src="../_static/flagicons/nl_NL.png" alt="nl_NL" title="nl_NL" border="0" /></a>
<a href="../pl/mapcache/install.html"><img src="../_static/flagicons/pl.png" alt="pl" title="pl" border="0" /></a>
<a href="../ru/mapcache/install.html"><img src="../_static/flagicons/ru.png" alt="ru" title="ru" border="0" /></a>
<a href="../sq/mapcache/install.html"><img src="../_static/flagicons/sq.png" alt="sq" title="sq" border="0" /></a>
<a href="../tr/mapcache/install.html"><img src="../_static/flagicons/tr.png" alt="tr" title="tr" border="0" /></a>
</td>
</tr>
</table>
<div class="related" role="navigation" aria-label="Related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="config.html" title="Configuration File"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="index.html" title="MapCache 1.16.0"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Home</a> »</li>
<li class="nav-item nav-item-1"><a href="../documentation.html" >MapServer 8.6.3 Documentation</a> »</li>
<li class="nav-item nav-item-2"><a href="index.html" accesskey="U">MapCache 1.16.0</a> »</li>
<li class="nav-item nav-item-this"><a href="">Compilation & Installation</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="compilation-installation">
<span id="mapcache-install"></span><h1><a class="toc-backref" href="#table-of-contents" role="doc-backlink">Compilation & Installation</a><a class="headerlink" href="#compilation-installation" title="Link to this heading">¶</a></h1>
<dl class="field-list simple">
<dt class="field-odd">Author<span class="colon">:</span></dt>
<dd class="field-odd"><p>Thomas Bonfort</p>
</dd>
<dt class="field-even">Contact<span class="colon">:</span></dt>
<dd class="field-even"><p>tbonfort at terriscope.fr</p>
</dd>
<dt class="field-odd">Author<span class="colon">:</span></dt>
<dd class="field-odd"><p>Alan Boudreault</p>
</dd>
<dt class="field-even">Contact<span class="colon">:</span></dt>
<dd class="field-even"><p>aboudreaut at magears.com</p>
</dd>
<dt class="field-odd">Author<span class="colon">:</span></dt>
<dd class="field-odd"><p>Jeff McKenna</p>
</dd>
<dt class="field-even">Contact<span class="colon">:</span></dt>
<dd class="field-even"><p>jmckenna at gatewaygeomatics.com</p>
</dd>
<dt class="field-odd">Author<span class="colon">:</span></dt>
<dd class="field-odd"><p>Mathieu Coudert</p>
</dd>
<dt class="field-even">Contact<span class="colon">:</span></dt>
<dd class="field-even"><p>mathieu.coudert at gmail.com</p>
</dd>
<dt class="field-odd">Author<span class="colon">:</span></dt>
<dd class="field-odd"><p>Seth Girvin</p>
</dd>
<dt class="field-even">Contact<span class="colon">:</span></dt>
<dd class="field-even"><p>sgirvin at compass.ie</p>
</dd>
<dt class="field-odd">Last Updated<span class="colon">:</span></dt>
<dd class="field-odd"><p>2026-04-20</p>
</dd>
</dl>
<nav class="contents" id="table-of-contents">
<p class="topic-title">Table of Contents</p>
<ul class="simple">
<li><p><a class="reference internal" href="#compilation-installation" id="id1">Compilation & Installation</a></p>
<ul>
<li><p><a class="reference internal" href="#getting-the-source" id="id2">Getting the Source</a></p></li>
<li><p><a class="reference internal" href="#linux-instructions" id="id3">Linux Instructions</a></p>
<ul>
<li><p><a class="reference internal" href="#apache-module-specific-instructions" id="id4">Apache Module Specific Instructions</a></p></li>
<li><p><a class="reference internal" href="#nginx-specific-instructions" id="id5">nginx Specific Instructions</a></p></li>
<li><p><a class="reference internal" href="#cgi-fastcgi-specific-instructions" id="id6">CGI/FastCGI Specific Instructions</a></p></li>
<li><p><a class="reference internal" href="#customizing-the-build-or-if-something-went-wrong" id="id7">Customizing the Build, Or If Something Went Wrong</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#windows-instructions" id="id8">Windows Instructions</a></p>
<ul>
<li><p><a class="reference internal" href="#dependencies" id="id9">Dependencies</a></p></li>
<li><p><a class="reference internal" href="#configure-your-makefile" id="id10">Configure Your Makefile</a></p></li>
<li><p><a class="reference internal" href="#compilation" id="id11">Compilation</a></p></li>
<li><p><a class="reference internal" href="#move-the-module-into-the-apache-directory" id="id12">Move the Module Into the Apache Directory</a></p></li>
<li><p><a class="reference internal" href="#configure-your-installed-apache" id="id13">Configure Your Installed Apache</a></p></li>
<li><p><a class="reference internal" href="#test-your-mapcache-module" id="id14">Test Your MapCache Module</a></p></li>
</ul>
</li>
</ul>
</li>
</ul>
</nav>
<section id="getting-the-source">
<h2><a class="toc-backref" href="#table-of-contents" role="doc-backlink">Getting the Source</a><a class="headerlink" href="#getting-the-source" title="Link to this heading">¶</a></h2>
<p>The MapCache project is located at <a class="reference external" href="https://github.com/MapServer/mapcache">https://github.com/MapServer/mapcache</a>, and can be checked out
with either:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># readonly</span>
git<span class="w"> </span>clone<span class="w"> </span>https://github.com/MapServer/mapcache.git
<span class="c1"># ssh authenticated</span>
git<span class="w"> </span>clone<span class="w"> </span>git@github.com:MapServer/mapcache.git
<span class="c1"># tarball</span>
wget<span class="w"> </span>https://github.com/MapServer/mapcache/zipball/main
</pre></div>
</div>
</section>
<section id="linux-instructions">
<h2><a class="toc-backref" href="#table-of-contents" role="doc-backlink">Linux Instructions</a><a class="headerlink" href="#linux-instructions" title="Link to this heading">¶</a></h2>
<p>These instructions target a Debian/Ubuntu setup, but should apply with few
modifications to any Linux installation.</p>
<p>MapCache requires a number of library headers in order to compile correctly:</p>
<ul class="simple">
<li><p><strong>apache / apr / apr-util / apx2</strong>: these are included in the <em>apache2-prefork-dev</em> or
<em>apache2-threaded-dev</em> packages, depending on which Apache MPM you are running.
This package will pull in the necessary APR headers that you would have to
manually install if you are not building an Apache module (<em>libaprutil1-dev</em>
and <em>libapr1-dev</em>)</p></li>
<li><p><strong>png</strong>: <em>libpng12-dev</em></p></li>
<li><p><strong>jpeg</strong>: <em>libjpeg62-dev</em></p></li>
<li><p><strong>curl</strong>: <em>libcurl4-gnutls-dev</em></p></li>
</ul>
<p>The following libraries are not required, but recommended:</p>
<ul class="simple">
<li><p><strong>pcre</strong>: <em>libpcre3-dev</em>. This will give you more powerful regular expression
syntax when creating validation expressions for dimensions</p></li>
<li><p><strong>pixman</strong>: <em>libpixman-1-dev</em>. The pixel manipulation library is used for
scaling and alpha-compositing images. MapCache ships with some code to
perform these tasks, but Pixman is generally faster as it includes
code optimized for modern CPUs (SSE2, MMX, etc…)</p></li>
</ul>
<p>The following libraries are not required, but needed to enable additional
functionalities:</p>
<ul class="simple">
<li><p><strong>fcgi</strong>: <em>libfcgi-dev</em>. Needed to build a FastCGI program if you don’t want to
run MapCache as an Apache module</p></li>
<li><p><strong>gdal / geos</strong>: <em>libgdal1-dev</em> <em>libgeos-dev</em>. Needed to enable advanced seeding
options (for only seeding tiles that intersect a given geographical feature)</p></li>
<li><p><strong>sqlite</strong>: <em>libsqlite3-dev</em>. For enabling the SQLite backend storage</p></li>
<li><p><strong>tiff</strong>: <em>libtiff4-dev</em>. For enabling the TIFF backend storage</p></li>
<li><p><strong>berkeley db</strong> <em>libdb4.8-dev</em> : For enabling the Berkeley DB backend storage</p></li>
<li><p><strong>lmdb</strong> <em>liblmdb-dev</em> : For enabling the Lightning Memory-Mapped Database backend storage
(available since MapCache 1.14.0 release)</p></li>
</ul>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>MapCache now builds with CMake.</p>
</div>
<p>For Unix users installing all packages to the default locations, the compilation
process should continue with:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span><span class="nb">cd</span><span class="w"> </span>mapcache
$<span class="w"> </span>mkdir<span class="w"> </span>build
$<span class="w"> </span><span class="nb">cd</span><span class="w"> </span>build
$<span class="w"> </span>cmake<span class="w"> </span>..
$<span class="w"> </span><span class="c1"># follow instructions below if missing a dependency</span>
$<span class="w"> </span>make
$<span class="w"> </span>sudo<span class="w"> </span>make<span class="w"> </span>install
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>If you receive a CMake error such as “Could NOT find APACHE (missing: APACHE_INCLUDE_DIR)”,
CMake needs to locate the <em>httpd.h</em> header file, and <em>apxs</em> or <em>apxs2</em>
executables, so you may need to install those specific packages (such as
on Ubuntu with the command <em>apt-get install apache2-dev</em>) and re-run the
cmake command.</p>
</div>
<section id="apache-module-specific-instructions">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">Apache Module Specific Instructions</a><a class="headerlink" href="#apache-module-specific-instructions" title="Link to this heading">¶</a></h3>
<p>The make install above installs the Apache module, but if you
specifically need to install only the Apache module you can do the following:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>sudo<span class="w"> </span>make<span class="w"> </span>install-module
$<span class="w"> </span>sudo<span class="w"> </span>ldconfig
</pre></div>
</div>
<p>The installation script takes care of putting the built module in the Apache
module directory. The process for activating a module is usually distro
specific, but can be resumed by the following snippet that should be present in
the Apache configuration file ( e.g. /usr/local/httpd/conf/httpd.conf or
/etc/apache2/sites-available/default ):</p>
<div class="highlight-apache notranslate"><div class="highlight"><pre><span></span><span class="nb">LoadModule</span><span class="w"> </span>mapcache_module<span class="w"> </span>modules/mod_mapcache.so
</pre></div>
</div>
<p>Next, a MapCache configuration is mapped to the server URL with the following
snippet:</p>
<p>For Apache < 2.4:</p>
<div class="highlight-apache notranslate"><div class="highlight"><pre><span></span><span class="nt"><IfModule</span><span class="w"> </span><span class="s">mapcache_module</span><span class="nt">></span>
<span class="w"> </span><span class="nt"><Directory</span><span class="w"> </span><span class="s">/path/to/directory</span><span class="nt">></span>
<span class="w"> </span><span class="nb">Order</span><span class="w"> </span>Allow,Deny
<span class="w"> </span><span class="nb">Allow</span><span class="w"> </span>from<span class="w"> </span><span class="k">all</span>
<span class="w"> </span><span class="nt"></Directory></span>
<span class="w"> </span><span class="nb">MapCacheAlias</span><span class="w"> </span><span class="sx">/mapcache</span><span class="w"> </span><span class="s2">"/path/to/directory/mapcache.xml"</span>
<span class="nt"></IfModule></span>
</pre></div>
</div>
<p>For Apache >= 2.4:</p>
<div class="highlight-apache notranslate"><div class="highlight"><pre><span></span><span class="nt"><IfModule</span><span class="w"> </span><span class="s">mapcache_module</span><span class="nt">></span>
<span class="w"> </span><span class="nt"><Directory</span><span class="w"> </span><span class="s">/path/to/directory</span><span class="nt">></span>
<span class="w"> </span><span class="nb">Require</span><span class="w"> </span><span class="k">all</span><span class="w"> </span>granted
<span class="w"> </span><span class="nt"></Directory></span>
<span class="w"> </span><span class="nb">MapCacheAlias</span><span class="w"> </span><span class="sx">/mapcache</span><span class="w"> </span><span class="s2">"/path/to/directory/mapcache.xml"</span>
<span class="nt"></IfModule></span>
</pre></div>
</div>
<p>Before you restart, copy the example mapcache.xml file to the location specified in your Apache configuration:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>cp<span class="w"> </span>mapcache.xml<span class="w"> </span>/path/to/directory/mapcache.xml
</pre></div>
</div>
<p>Finally, restart Apache to take the modified configuration into account</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>sudo<span class="w"> </span>apachectl<span class="w"> </span>restart
</pre></div>
</div>
<p>If you have not disabled the demo service, you should now have access to it on
<a class="reference external" href="http://myserver/mapcache/demo">http://myserver/mapcache/demo</a></p>
</section>
<section id="nginx-specific-instructions">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">nginx Specific Instructions</a><a class="headerlink" href="#nginx-specific-instructions" title="Link to this heading">¶</a></h3>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>Working with nginx is still somewhat experimental. The following
workflow has only been tested on the development version, i.e.
nginx-1.1.x</p>
</div>
<p>For nginx support you need to build MapCache’s nginx module against the
nginx source. Download the nginx source code:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span><span class="nb">cd</span><span class="w"> </span>/usr/local/src
$<span class="w"> </span>mkdir<span class="w"> </span>nginx
$<span class="w"> </span><span class="nb">cd</span><span class="w"> </span>nginx
$<span class="w"> </span>wget<span class="w"> </span>http://nginx.org/download/nginx-1.1.19.tar.gz
$<span class="w"> </span>tar<span class="w"> </span>-xzvf<span class="w"> </span>nginx-1.1.19.tar.gz
$<span class="w"> </span><span class="nb">cd</span><span class="w"> </span>nginx-1.1.19/
</pre></div>
</div>
<p>Run the configure command with the flag <cite>–add-module</cite>. This flag
must point to MapCache’s nginx child directory. Assuming that the
MapServer source was cloned or extracted into to <cite>/usr/local/src</cite>,
an example configure command for nginx would look like this:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>./configure<span class="w"> </span>--add-module<span class="o">=</span>/usr/local/src/mapcache/nginx
</pre></div>
</div>
<p>Then build nginx:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>make
$<span class="w"> </span>sudo<span class="w"> </span>make<span class="w"> </span>install
</pre></div>
</div>
<p>Due to nginx’s non-blocking architecture, the MapCache nginx module does not
perform any operations that may lead to a worker process being blocked by a
long computation (i.e.: requesting a (meta)tile to be rendered if not in the
cache, proxying a request to an upstream WMS server, or waiting for a tile to
be rendered by another worker): It will instead issue a 404 error. This
behavior is essential so as not to occupy all nginx worker threads, thereby
preventing it from responding to all other incoming requests. While this isn’t
an issue for completely seeded tilesets, it implies that these kinds of
requests need to be proxied to another MapCache instance that does not suffer
from these starvation issues (i.e. either a FastCGI MapCache, or an internal
proxied Apache server). In this scenario, both the nginx MapCache instance and
the Apache/FastCGI MapCache instance should be running with the same
<cite>mapcache.xml</cite> configuration file.</p>
<p>MapCache supplies an <cite>nginx.conf</cite> in its nginx child directory. The conf
contains an example configuration to load MapCache. The most relevant part of
the configuration is the location directive that points the <cite>^/mapcache</cite> URI
to the <cite>mapcache.xml</cite> path. You will need to change this path to point to
your own <cite>mapcache.xml</cite> in the MapCache source.</p>
<p>The basic configuration without any proxying (which will return 404 errors on
unseeded tile requests) is:</p>
<div class="highlight-nginx notranslate"><div class="highlight"><pre><span></span><span class="k">location</span><span class="w"> </span><span class="p">~</span><span class="w"> </span><span class="sr">^/mapcache(?<path_info>/.*|$)</span><span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="kn">set</span><span class="w"> </span><span class="nv">$url_prefix</span><span class="w"> </span><span class="s">"/mapcache"</span><span class="p">;</span>
<span class="w"> </span><span class="kn">mapcache</span><span class="w"> </span><span class="s">/usr/local/src/mapcache/mapcache.xml</span><span class="p">;</span>
<span class="p">}</span>
</pre></div>
</div>
<p>If proxying unseeded tile requests to a MapCache instance running on an Apache
server, we will proxy all 404 MapCache errors to a <cite>mapcache.apache.tld</cite>
server listening on port 8080, configured to respond to MapCache requests on
the <cite>/mapcache</cite> location.</p>
<div class="highlight-nginx notranslate"><div class="highlight"><pre><span></span><span class="k">location</span><span class="w"> </span><span class="p">~</span><span class="w"> </span><span class="sr">^/mapcache(?<path_info>/.*|$)</span><span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="kn">set</span><span class="w"> </span><span class="nv">$url_prefix</span><span class="w"> </span><span class="s">"/mapcache"</span><span class="p">;</span>
<span class="w"> </span><span class="kn">mapcache</span><span class="w"> </span><span class="s">/usr/local/src/mapcache/mapcache.xml</span><span class="p">;</span>
<span class="w"> </span><span class="kn">error_page</span><span class="w"> </span><span class="mi">404</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="s">@apache_mapcache</span><span class="p">;</span>
<span class="p">}</span>
<span class="k">location</span><span class="w"> </span><span class="s">@apache_mapcache</span><span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="kn">proxy_pass</span><span class="w"> </span><span class="s">http://mapcache.apache.tld:8080</span><span class="p">;</span>
<span class="p">}</span>
</pre></div>
</div>
<p>If using FastCGI instances of MapCache, spawned with e.g. spawn-fcgi or
supervisord on port 9001 (make sure to enable FastCGI when building MapCache,
and to set the MAPCACHE_CONFIG_FILE environment variable before spawning):</p>
<div class="highlight-nginx notranslate"><div class="highlight"><pre><span></span><span class="k">location</span><span class="w"> </span><span class="p">~</span><span class="w"> </span><span class="sr">^/mapcache(?<path_info>/.*|$)</span><span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="kn">set</span><span class="w"> </span><span class="nv">$url_prefix</span><span class="w"> </span><span class="s">"/mapcache"</span><span class="p">;</span>
<span class="w"> </span><span class="kn">mapcache</span><span class="w"> </span><span class="s">/usr/local/src/mapcache/mapcache.xml</span><span class="p">;</span>
<span class="w"> </span><span class="kn">error_page</span><span class="w"> </span><span class="mi">404</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="s">@fastcgi_mapcache</span><span class="p">;</span>
<span class="p">}</span>
<span class="k">location</span><span class="w"> </span><span class="s">@fastcgi_mapcache</span><span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="kn">fastcgi_pass</span><span class="w"> </span><span class="n">localhost</span><span class="p">:</span><span class="mi">9001</span><span class="p">;</span>
<span class="w"> </span><span class="kn">fastcgi_param</span><span class="w"> </span><span class="s">QUERY_STRING</span><span class="w"> </span><span class="nv">$query_string</span><span class="p">;</span>
<span class="w"> </span><span class="kn">fastcgi_param</span><span class="w"> </span><span class="s">REQUEST_METHOD</span><span class="w"> </span><span class="nv">$request_method</span><span class="p">;</span>
<span class="w"> </span><span class="kn">fastcgi_param</span><span class="w"> </span><span class="s">CONTENT_TYPE</span><span class="w"> </span><span class="nv">$content_type</span><span class="p">;</span>
<span class="w"> </span><span class="kn">fastcgi_param</span><span class="w"> </span><span class="s">CONTENT_LENGTH</span><span class="w"> </span><span class="nv">$content_length</span><span class="p">;</span>
<span class="w"> </span><span class="kn">fastcgi_param</span><span class="w"> </span><span class="s">PATH_INFO</span><span class="w"> </span><span class="nv">$path_info</span><span class="p">;</span>
<span class="w"> </span><span class="kn">fastcgi_param</span><span class="w"> </span><span class="s">SERVER_NAME</span><span class="w"> </span><span class="nv">$server_name</span><span class="p">;</span>
<span class="w"> </span><span class="kn">fastcgi_param</span><span class="w"> </span><span class="s">SERVER_PORT</span><span class="w"> </span><span class="nv">$server_port</span><span class="p">;</span>
<span class="w"> </span><span class="kn">fastcgi_param</span><span class="w"> </span><span class="s">SCRIPT_NAME</span><span class="w"> </span><span class="s">"/mapcache"</span><span class="p">;</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Copy the relevant sections of <cite>nginx.conf</cite> from MapCache’s <cite>nginx</cite>
directory into nginx’s conf file (in this case
<cite>/usr/local/nginx/conf/nginx.conf</cite>). You should now have access to the demo
at <a class="reference external" href="http://myserver/mapcache/demo">http://myserver/mapcache/demo</a></p>
</section>
<section id="cgi-fastcgi-specific-instructions">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">CGI/FastCGI Specific Instructions</a><a class="headerlink" href="#cgi-fastcgi-specific-instructions" title="Link to this heading">¶</a></h3>
<p>A binary CGI/FastCGI is located in the mapcache/ subfolder, and is named “mapcache”.
Activating FastCGI for the MapCache program on your web server is not part of
these instructions; more details may be found on the <a class="reference internal" href="../optimization/fastcgi.html#fastcgi"><span class="std std-ref">FastCGI</span></a>
page or on more general pages across the web.</p>
<p>The MapCache FastCGI program looks for its configuration file in the environment
variable called MAPCACHE_CONFIG_FILE, which must be set by the web server before
spawning the MapCache processes.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="config.html#mapcache-config"><span class="std std-ref">Configuration File</span></a></p>
</div>
<section id="apache-with-mod-cgi">
<h4>Apache with mod_cgi<a class="headerlink" href="#apache-with-mod-cgi" title="Link to this heading">¶</a></h4>
<div class="highlight-apache notranslate"><div class="highlight"><pre><span></span><span class="nb">SetEnv</span><span class="w"> </span><span class="s2">"MAPCACHE_CONFIG_FILE"</span><span class="w"> </span><span class="s2">"/path/to/mapcache/mapcache.xml"</span>
</pre></div>
</div>
<p>For Apache with mod_fcgid:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">FcgidInitialEnv</span> <span class="s2">"MAPCACHE_CONFIG_FILE"</span> <span class="s2">"/path/to/mapcache/mapcache.xml</span>
</pre></div>
</div>
<p>If you have not disabled the demo service, you should now have access to it on
<a class="reference external" href="http://myserver/fcgi-bin/mapcache/demo">http://myserver/fcgi-bin/mapcache/demo</a>, assuming your fcgi processes are accessed
under the fcgi-bin alias.</p>
<p>With a working mod_fcgid Apache instance, the full httpd.conf snippet to activate
MapCache could be:</p>
<div class="highlight-apache notranslate"><div class="highlight"><pre><span></span><span class="nt"><IfModule</span><span class="w"> </span><span class="s">mod_fcgid.c</span><span class="nt">></span>
<span class="w"> </span><span class="nb">IPCCommTimeout</span><span class="w"> </span><span class="m">120</span>
<span class="w"> </span><span class="nb">MaxProcessCount</span><span class="w"> </span><span class="m">10</span>
<span class="w"> </span><span class="nb">FcgidInitialEnv</span><span class="w"> </span><span class="s2">"MAPCACHE_CONFIG_FILE"</span><span class="w"> </span><span class="s2">"/path/to/mapcache/mapcache.xml"</span>
<span class="w"> </span><span class="nt"><Location</span><span class="w"> </span><span class="s">/map.fcgi</span><span class="nt">></span>
<span class="w"> </span><span class="nb">Order</span><span class="w"> </span>Allow,Deny
<span class="w"> </span><span class="nb">Allow</span><span class="w"> </span>from<span class="w"> </span><span class="k">all</span>
<span class="w"> </span><span class="nb">SetHandler</span><span class="w"> </span>fcgid-script
<span class="w"> </span><span class="nt"></Location></span>
<span class="w"> </span><span class="nb">ScriptAlias</span><span class="w"> </span><span class="sx">/map.fcgi</span><span class="w"> </span><span class="s2">"/path/to/mapcache/src/mapcache"</span>
<span class="nt"></IfModule></span>
</pre></div>
</div>
<p>The MapCache service would then be accessible at <a class="reference external" href="http://myserver/map.fcgi[/demo">http://myserver/map.fcgi[/demo</a>]</p>
</section>
<section id="iis-and-fastcgi">
<h4>IIS and FastCGI<a class="headerlink" href="#iis-and-fastcgi" title="Link to this heading">¶</a></h4>
<p>First ensure FastCGI has been installed - see the notes on configuring <a class="reference internal" href="../installation/iis.html#iis-configuration"><span class="std std-ref">MapServer in IIS</span></a>.
MapCache relies on the <code class="docutils literal notranslate"><span class="pre">MAPCACHE_CONFIG_FILE</span></code> environment variable to be set in IIS. See the MapServer
<a class="reference internal" href="../installation/iis.html#iis-environ-settings"><span class="std std-ref">further configuration</span></a> on how to set this.</p>
<p>To create the variable from the command line you can use the following (which requires administrator privileges):</p>
<div class="highlight-bat notranslate"><div class="highlight"><pre><span></span><span class="nv">%windir%</span>\system32\inetsrv\appcmd.exe set config -section:system.webServer/fastCgi /+<span class="s2">"[fullPath='C:\Mapserver\bin\mapcache.fcgi.exe'].environmentVariables.[name='MAPCACHE_CONFIG_FILE',value='C:\MapServer\apps\cache1.xml']"</span> /commit:apphost
</pre></div>
</div>
<p>Often you will want to use different MapCache configuration files for different web applications on the same server. To set these
up you need to set a unique argument that will be passed to <code class="docutils literal notranslate"><span class="pre">mapcache.fcgi.exe</span></code>.</p>
<div class="highlight-bat notranslate"><div class="highlight"><pre><span></span><span class="nv">%windir%</span>\system32\inetsrv\appcmd.exe set config -section:system.webServer/fastCgi /+<span class="s2">"[fullPath='C:\Mapserver\bin\mapcache.fcgi.exe',arguments='cache2']"</span> /commit:apphost
<span class="nv">%windir%</span>\system32\inetsrv\appcmd.exe set config -section:system.webServer/fastCgi /+<span class="s2">"[fullPath='C:\Mapserver\bin\mapcache.fcgi.exe',arguments='cache2'].environmentVariables.[name='MAPCACHE_CONFIG_FILE',value='C:\MapServer\apps\cache2.xml']"</span> /commit:apphost
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>It appears the command has to be run in two parts or the following error is returned
<code class="docutils literal notranslate"><span class="pre">ERROR</span> <span class="pre">(</span> <span class="pre">message:Cannot</span> <span class="pre">find</span> <span class="pre">requested</span> <span class="pre">collection</span> <span class="pre">element.</span> <span class="pre">)</span></code>.</p>
</div>
<p>FastCGI configurations are stored in <code class="docutils literal notranslate"><span class="pre">C:\Windows\System32\inetsrv\config\applicationHost.config</span></code>. The commands creates
the following XML:</p>
<div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="nt"><application</span><span class="w"> </span><span class="na">fullPath=</span><span class="s">"C:\Mapserver\bin\mapcache.fcgi.exe"</span><span class="w"> </span><span class="na">arguments=</span><span class="s">"cache2"</span><span class="nt">></span>
<span class="w"> </span><span class="nt"><environmentVariables></span>
<span class="w"> </span><span class="nt"><environmentVariable</span><span class="w"> </span><span class="na">name=</span><span class="s">"MAPCACHE_CONFIG_FILE"</span><span class="w"> </span><span class="na">value=</span><span class="s">"C:\MapServer\apps\cache2.xml"</span><span class="w"> </span><span class="nt">/></span>
<span class="w"> </span><span class="nt"></environmentVariables></span>
<span class="nt"></application></span>
</pre></div>
</div>
<p>Now we have set <code class="docutils literal notranslate"><span class="pre">MAPCACHE_CONFIG_FILE</span></code> we can configure a web application to use MapCache. This can all be done through the web application’s
<code class="docutils literal notranslate"><span class="pre">web.config</span></code> file. Below is a sample configuration:</p>
<div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="cp"><?xml version="1.0" encoding="UTF-8"?></span>
<span class="nt"><configuration></span>
<span class="w"> </span><span class="nt"><system.webServer></span>
<span class="w"> </span><span class="nt"><handlers></span>
<span class="w"> </span><span class="nt"><add</span><span class="w"> </span><span class="na">name=</span><span class="s">"mapcache"</span>
<span class="w"> </span><span class="na">path=</span><span class="s">"/*"</span><span class="w"> </span><span class="na">verb=</span><span class="s">"*"</span><span class="w"> </span><span class="na">modules=</span><span class="s">"FastCgiModule"</span>
<span class="w"> </span><span class="na">scriptProcessor=</span><span class="s">"C:\MapServer\bin\mapcache.fcgi.exe|cache2"</span>
<span class="w"> </span><span class="na">resourceType=</span><span class="s">"Unspecified"</span>
<span class="w"> </span><span class="na">requireAccess=</span><span class="s">"Script"</span>
<span class="w"> </span><span class="na">allowPathInfo=</span><span class="s">"true"</span><span class="w"> </span><span class="nt">/></span>
<span class="w"> </span><span class="nt"></handlers></span>
<span class="w"> </span><span class="nt"></system.webServer></span>
<span class="nt"></configuration></span>
</pre></div>
</div>
<p>Key points to note are:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">allowPathInfo</span></code> must be set to <code class="docutils literal notranslate"><span class="pre">true</span></code> so IIS handles the <code class="docutils literal notranslate"><span class="pre">PATH_INFO</span></code> in the same way as other web servers (otherwise
IIS duplicates the <code class="docutils literal notranslate"><span class="pre">SCRIPT_NAME</span></code> in <code class="docutils literal notranslate"><span class="pre">PATH_INFO</span></code> breaking how MapCache handles URLs).</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">scriptProcessor</span></code> should be set to match the <code class="docutils literal notranslate"><span class="pre">fullPath</span></code> set when creating the FastCGI configuration. The <code class="docutils literal notranslate"><span class="pre">|cache2</span></code> should
match the argument for the FastCGI application, separated from the path with a pipe (|) character.</p></li>
<li><p>If you have a FastCGI application without any arguments (when running a single instance of MapCache) you do not need to add the pipe and argument
to <code class="docutils literal notranslate"><span class="pre">scriptProcessor</span></code>.</p></li>
</ul>
<p>The MapCache service should then be accessible at <a class="reference external" href="http://localhost/mapcache/demo/">http://localhost/mapcache/demo/</a></p>
</section>
</section>
<section id="customizing-the-build-or-if-something-went-wrong">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">Customizing the Build, Or If Something Went Wrong</a><a class="headerlink" href="#customizing-the-build-or-if-something-went-wrong" title="Link to this heading">¶</a></h3>
<p>Depending on which packages are available in the default locations of your system,
the “cmake ..” step will most probably have failed with messages indicating
missing dependencies (by default, MapCache has <em>some</em> of those). The error message
that CMake prints out should give you a rather good idea of what steps you should take
next, depending on whether the failed dependency is a feature you require in your build.</p>
<p>mod_mapcache requires Apache, libcurl, libjpeg and libpng development headers.
The CMake script will try to locate them in default system locations, but these locations can be
overridden or specified with -D switches. For example, if you get a message such as
‘Could NOT find APR ‘, you can use a command such as
(assuming that APR is at /usr/local/apr) :</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>cmake<span class="w"> </span>-DCMAKE_PREFIX_PATH<span class="o">=</span><span class="s2">"/usr/local/apr;"</span><span class="w"> </span>..
</pre></div>
</div>
<p>If you don’t want e.g. fcgi, you can disable the dependency by re-running CMake with -DWITH_DEPENDENCY=0, e.g.</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>cmake<span class="w"> </span>..<span class="w"> </span>-DWITH_FCGI<span class="o">=</span><span class="m">0</span>
</pre></div>
</div>
<section id="options-supported-by-the-mapcache-cmake-builder">
<h4>Options Supported By the MapCache CMake Builder<a class="headerlink" href="#options-supported-by-the-mapcache-cmake-builder" title="Link to this heading">¶</a></h4>
<p>Here is a list of supported options that can be enabled/disabled at build.</p>
<blockquote>
<div><div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">option</span><span class="p">(</span><span class="n">WITH_PIXMAN</span> <span class="s2">"Use Pixman for SSE optimized image manipulations"</span> <span class="n">ON</span><span class="p">)</span>
<span class="n">option</span><span class="p">(</span><span class="n">WITH_SQLITE</span> <span class="s2">"Use SQLite as a cache backend"</span> <span class="n">ON</span><span class="p">)</span>
<span class="n">option</span><span class="p">(</span><span class="n">WITH_BERKELEY_DB</span> <span class="s2">"Use Berkeley DB as a cache backend"</span> <span class="n">OFF</span><span class="p">)</span>
<span class="n">option</span><span class="p">(</span><span class="n">WITH_LMDB</span> <span class="s2">"Use LMDB as a cache backend"</span> <span class="n">OFF</span><span class="p">)</span>
<span class="n">option</span><span class="p">(</span><span class="n">WITH_MEMCACHE</span> <span class="s2">"Use memcache as a cache backend (requires recent apr-util)"</span> <span class="n">OFF</span><span class="p">)</span>
<span class="n">option</span><span class="p">(</span><span class="n">WITH_TIFF</span> <span class="s2">"Use TIFFs as a cache backend"</span> <span class="n">OFF</span><span class="p">)</span>
<span class="n">option</span><span class="p">(</span><span class="n">WITH_TIFF_WRITE_SUPPORT</span> <span class="s2">"Enable (experimental) support for writable TIFF cache backends"</span> <span class="n">OFF</span><span class="p">)</span>
<span class="n">option</span><span class="p">(</span><span class="n">WITH_GEOTIFF</span> <span class="s2">"Allow GeoTIFF metadata creation for TIFF cache backends"</span> <span class="n">OFF</span><span class="p">)</span>
<span class="n">option</span><span class="p">(</span><span class="n">WITH_PCRE</span> <span class="s2">"Use PCRE for regex tests"</span> <span class="n">OFF</span><span class="p">)</span>
<span class="n">option</span><span class="p">(</span><span class="n">WITH_MAPSERVER</span> <span class="s2">"Enable (experimental) support for the MapServer library"</span> <span class="n">OFF</span><span class="p">)</span>
<span class="n">option</span><span class="p">(</span><span class="n">WITH_POSTGRESQL</span> <span class="s2">"Use PostgreSQL as a dimension backend"</span> <span class="n">OFF</span><span class="p">)</span>
<span class="n">option</span><span class="p">(</span><span class="n">WITH_RIAK</span> <span class="s2">"Use Riak as a cache backend"</span> <span class="n">OFF</span><span class="p">)</span>
<span class="n">option</span><span class="p">(</span><span class="n">WITH_GDAL</span> <span class="s2">"Choose if GDAL raster support should be built in"</span> <span class="n">ON</span><span class="p">)</span>
<span class="n">option</span><span class="p">(</span><span class="n">WITH_MAPCACHE_DETAIL</span> <span class="s2">"Build coverage analysis tool for SQLite caches"</span> <span class="n">ON</span><span class="p">)</span>
<span class="n">option</span><span class="p">(</span><span class="n">WITH_GEOS</span> <span class="s2">"Choose whether GEOS geometry operations support should be built in"</span> <span class="n">ON</span><span class="p">)</span>
<span class="n">option</span><span class="p">(</span><span class="n">WITH_OGR</span> <span class="s2">"Choose whether OGR/GDAL input vector support should be built in"</span> <span class="n">ON</span><span class="p">)</span>
<span class="n">option</span><span class="p">(</span><span class="n">WITH_CGI</span> <span class="s2">"Choose whether CGI executable should be built"</span> <span class="n">ON</span><span class="p">)</span>
<span class="n">option</span><span class="p">(</span><span class="n">WITH_FCGI</span> <span class="s2">"Choose whether CGI executable should support FastCGI"</span> <span class="n">ON</span><span class="p">)</span>
<span class="n">option</span><span class="p">(</span><span class="n">WITH_VERSION_STRING</span> <span class="s2">"Show MapCache in server version string"</span> <span class="n">ON</span><span class="p">)</span>
<span class="n">option</span><span class="p">(</span><span class="n">WITH_APACHE</span> <span class="s2">"Build Apache Module"</span> <span class="n">ON</span><span class="p">)</span>
</pre></div>
</div>
<ul>
<li><p><strong>Pixman</strong> (<em>recommended</em>, from 0.5 onwards)</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>-DWITH_PIXMAN<span class="o">=[</span><span class="m">0</span><span class="p">|</span><span class="m">1</span><span class="o">]</span>
</pre></div>
</div>
<p>Pixman is a pixel manipulation library used to assemble image tiles when
responding to non-tiled WMS requests. Pixman support is recommended as it is
highly optimized and will take advantage of recent processor extensions (MMX,
SSE2, etc.) to speed up blending and resampling operations. If the Pixman
library is not found, MapCache will fall back to internal pixel operations
that are slower.</p>
</li>
<li><p><strong>SQLite</strong> (<em>optional</em>, from 0.5 onwards)</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>-DWITH_SQLITE<span class="o">=[</span><span class="m">0</span><span class="p">|</span><span class="m">1</span><span class="o">]</span>
</pre></div>
</div>
<p>SQLite is used to enable the SQLite and MBTiles cache backend. Version 3.5.0
or newer is required.</p>
</li>
<li><p><strong>GDAL</strong> (<em>optional</em>, from 0.4 onwards, also requires geos)</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>-DWITH_OGR<span class="o">=[</span><span class="m">0</span><span class="p">|</span><span class="m">1</span><span class="o">]</span>
</pre></div>
</div>
<p>GDAL (actually OGR) is used by the seeding utility to allow the seeding of
tiles only intersecting a given polygon, e.g. to pre-seed all the tiles of a
given country.</p>
</li>
<li><p><strong>GEOS</strong> (<em>optional</em>, from 0.5 onwards)</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>-DWITH_GEOS<span class="o">=[</span><span class="m">0</span><span class="p">|</span><span class="m">1</span><span class="o">]</span>
</pre></div>
</div>
<p>Along with GDAL/OGR, GEOS is needed by the seeder to test for the intersection
of tiles with geographical features. A sufficiently recent version of GEOS (with
support for prepared geometries) is required (but not enforced by the configure
script, so you’ll end up with compilation errors if a too old GEOS version is
used).</p>
</li>
<li><p><strong>PCRE</strong> (<em>optional</em>)</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>-DWITH_PCRE<span class="o">=[</span><span class="m">0</span><span class="p">|</span><span class="m">1</span><span class="o">]</span>
</pre></div>
</div>
<p>PCRE (Perl Compatible Regular Expressions) can be used instead of POSIX regular
expressions for validating WMS dimensions. They are more powerful than POSIX
REs (and might be slower). You don’t need this if you aren’t planning on using
WMS dimension support with regex validation, or if your validation needs are
covered by posix REs.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="dimensions.html#mapcache-dimensions"><span class="std std-ref">Tileset Dimensions</span></a></p>
</div>
</li>
<li><p><strong>FastCGI Support</strong> (<em>optional</em>)</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>-DWITH_FCGI<span class="o">=[</span><span class="m">0</span><span class="p">|</span><span class="m">1</span><span class="o">]</span>
</pre></div>
</div>
<p>MapCache can run as a FastCGI executable. Note that the overhead of FastCGI
is non-negligible with respect to the throughput you may obtain with a native
Apache module. The FastCGI build is less tested, and may lag behind
the Apache module version on some minor details. YMMV.</p>
</li>
<li><p><strong>TIFF read/write Cache Support</strong> (<em>optional</em>)</p>
<p>Use TIFFs as a cache backend (READONLY) :</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>-DWITH_TIFF<span class="o">=[</span><span class="m">0</span><span class="p">|</span><span class="m">1</span><span class="o">]</span>
</pre></div>
</div>
<p>TIFF write support (for creating new TIFF files and adding tiles to existing
TIFF files) is still experimental and disabled by default. There is a risk of
ending up with corrupt TIFF files if they are placed on a filesystem that does
not honor file locking, as in that case multiple processes might end up writing
to the same file. File locking across concurrent threads is also problematic,
although MapCache tries to detect this situation and apply sufficient locking
workarounds. To stay on the safe side, write support should for now only be
enabled on local filesystems, with a prefork MPM or FastCGI MapCache install.</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>-DWITH_TIFF_WRITE_SUPPORT<span class="o">=[</span><span class="m">0</span><span class="p">|</span><span class="m">1</span><span class="o">]</span>
</pre></div>
</div>
<p>When writing TIFF files, MapCache can also optionally add georeferencing
information if compiled with libtiff support. GeoTiff writing does not
produce the full tags needed for defining which projection the grid is
in, but will only produce those defining the pixel scale and the tiepoints
(i.e. the equivalent information found in the accompanying .tfw files).</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>-DWITH_GEOTIFF<span class="o">=[</span><span class="m">0</span><span class="p">|</span><span class="m">1</span><span class="o">]</span>
</pre></div>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="caches.html#mapcache-cache-tiff"><span class="std std-ref">(Geo)TIFF Caches</span></a></p>
</div>
</li>
<li><p><strong>Memcached Cache Support</strong> (<em>optional</em>)</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>-DWITH_MEMCACHE<span class="o">=[</span><span class="m">0</span><span class="p">|</span><span class="m">1</span><span class="o">]</span>
</pre></div>
</div>
<p>The memcached cache backend is disabled by default. You can optionally enable it as
it does not depend on other external libraries (support is obtained through apr-util).</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="caches.html#mapcache-cache-memcache"><span class="std std-ref">Memcache Caches</span></a></p>
</div>
</li>
<li><p><strong>Apache Module Options</strong></p>
<p>You can disable the Apache module building if you only plan on using the
FastCGI executable or the seeder.</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>-DWITH_APACHE<span class="o">=[</span><span class="m">0</span><span class="p">|</span><span class="m">1</span><span class="o">]</span>
</pre></div>
</div>
<p>MapCache adds itself to the version string reported by the Apache server. This
can be disabled with:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>-DWITH_VERSION_STRING<span class="o">=[</span><span class="m">0</span><span class="p">|</span><span class="m">1</span><span class="o">]</span>
</pre></div>
</div>
</li>
<li><p><strong>Native MapServer Mode</strong> (<em>experimental options</em>)</p>
<p>MapCache is by default not linked to MapServer in any way, and communicates
through the WMS protocol only. For improved performance, it is possible
to directly use the MapServer C library and avoid an HTTP request and an image
compression/decompression. This integration is still experimental and should
be used cautiously.</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>-DWITH_MAPSERVER<span class="o">=[</span><span class="m">0</span><span class="p">|</span><span class="m">1</span><span class="o">]</span>
</pre></div>
</div>
<p>This will use the libmapserver.so from MapServer’s install directory. MapServer
itself should be compiled with thread-safety enabled, unless you plan to use the
prefork MPM or FastCGI, <strong>and</strong> you do not plan to use the seeder. For thread
safety on the MapServer side, you might want to have a look at tickets #4041
and #4044.</p>
</li>
<li><p><strong>Debug Mode</strong> (<em>work in progress</em>)</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Since the CMake migration, this has to be done.</p>
</div>
<p>It enables some extra tests inside the code, and prints out many more debugging
messages to the server logs. you should probably not enable this unless you
want to track down a problem happening inside MapCache.</p>
</li>
</ul>
</div></blockquote>
</section>
</section>
</section>
<section id="windows-instructions">
<h2><a class="toc-backref" href="#table-of-contents" role="doc-backlink">Windows Instructions</a><a class="headerlink" href="#windows-instructions" title="Link to this heading">¶</a></h2>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>The following instructions are outdated. Windows builds are now handled
identically to the Unix ones with CMake.</p>
</div>
<p>These instructions target a Windows 7 setup with an Apache httpd compiled from
source. The Apache MapCache module has been successfully built with with
Microsoft Visual Studio C++ versions 2003, 2008 and 2010.</p>
<section id="dependencies">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">Dependencies</a><a class="headerlink" href="#dependencies" title="Link to this heading">¶</a></h3>
<p>Required:</p>
<ul class="simple">
<li><p><strong>Apache / APR / APR-UTIL</strong>: included with Apache httpd installation</p></li>
</ul>
<p>These can be installed manually, or using the appropriate Windows SDK
from: <a class="reference external" href="http://www.gisinternals.com/sdk/">http://www.gisinternals.com/sdk/</a></p>
<ul class="simple">
<li><p><strong>PNG</strong></p></li>
<li><p><strong>JPEG</strong></p></li>
<li><p><strong>CURL</strong></p></li>
</ul>
<p>Recommended:</p>
<ul class="simple">
<li><p><strong>PCRE</strong>: <a class="reference external" href="ftp://ftp.gnu.org/pub/gnu/regex/regex-0.12.tar.gz">ftp://ftp.gnu.org/pub/gnu/regex/regex-0.12.tar.gz</a></p></li>
</ul>
<p>Optional:</p>
<ul class="simple">
<li><p><strong>FCGI</strong>: Needed to build a FastCGI program if you don’t want to run
MapCache as an Apache module</p></li>
<li><p><strong>GDAL / GEOS</strong>: Needed to enable advanced seeding options (for only
seeding tiles that intersect a given geographical feature)</p></li>
<li><p><strong>SQLITE</strong>: For enabling the SQLite backend storage</p></li>
<li><p><strong>TIFF</strong>: For enabling the TIFF backend storage</p></li>
</ul>
</section>
<section id="configure-your-makefile">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">Configure Your Makefile</a><a class="headerlink" href="#configure-your-makefile" title="Link to this heading">¶</a></h3>
<p>Open nmake.opt and modify the paths to point to the various libraries.</p>
</section>
<section id="compilation">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">Compilation</a><a class="headerlink" href="#compilation" title="Link to this heading">¶</a></h3>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>nmake<span class="w"> </span>/f<span class="w"> </span>Makefile.vc
</pre></div>
</div>
<p>If successful, the resulting libraries and executables will be generated in their associated
directories:</p>
<dl class="simple">
<dt>apache/</dt><dd><p>Apache module (mod_mapcache.dll)</p>
</dd>
<dt>cgi/</dt><dd><p>FastCGI MapCache executable (mapcache.exe)</p>
</dd>
<dt>util/</dt><dd><p>MapCache utilities (mapcache_seed.exe)</p>
</dd>
</dl>
</section>
<section id="move-the-module-into-the-apache-directory">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">Move the Module Into the Apache Directory</a><a class="headerlink" href="#move-the-module-into-the-apache-directory" title="Link to this heading">¶</a></h3>
<p>Copy the <em>mod_mapcache.dll</em> file into one of your Apache subdirectories.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Although other modules are installed into <em>/Apache/modules/</em>, you should place
mod_mapcache.dll wherever its required dll files (libcurl.dll, zlib.dll, etc.) live,
to avoid any loading issues later on.</p>
</div>
</section>
<section id="configure-your-installed-apache">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">Configure Your Installed Apache</a><a class="headerlink" href="#configure-your-installed-apache" title="Link to this heading">¶</a></h3>
<ul>
<li><p>Modify your <em>httpd.conf</em> file to load the module:</p>
<div class="highlight-apache notranslate"><div class="highlight"><pre><span></span><span class="nb">LoadModule</span><span class="w"> </span>mapcache_module<span class="w"> </span><span class="s2">"D:/ms4w/Apache/cgi-bin/mod_mapcache.dll"</span>
</pre></div>
</div>
</li>
<li><p>Next, configure your MapCache directory with the following
snippet:</p>
<div class="highlight-apache notranslate"><div class="highlight"><pre><span></span><span class="nt"><IfModule</span><span class="w"> </span><span class="s">mapcache_module</span><span class="nt">></span>
<span class="w"> </span><span class="nt"><Directory</span><span class="w"> </span><span class="s">"D:/ms4w/apps/mapcache/"</span><span class="nt">></span>
<span class="w"> </span><span class="nb">Order</span><span class="w"> </span>Allow,Deny
<span class="w"> </span><span class="nb">Allow</span><span class="w"> </span>from<span class="w"> </span><span class="k">all</span>
<span class="w"> </span><span class="nt"></Directory></span>
<span class="w"> </span><span class="nb">MapCacheAlias</span><span class="w"> </span><span class="sx">/mapcache</span><span class="w"> </span><span class="s2">"D:/ms4w/apps/mapcache/mapcache.xml"</span>
<span class="nt"></IfModule></span>
</pre></div>
</div>
</li>
<li><p>Configure your <em>mapcache.xml</em> file (see the <a class="reference internal" href="config.html#mapcache-config"><span class="std std-ref">Configuration</span></a> section
for help).</p>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>If you receive an error such as “cache disk: host system does not support file symbolic linking”
you should comment out the line “<symlink_blank/>” in your mapcache.xml file, such as the following:</p>
</div>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><cache<span class="w"> </span><span class="nv">name</span><span class="o">=</span><span class="s2">"disk"</span><span class="w"> </span><span class="nv">type</span><span class="o">=</span><span class="s2">"disk"</span>>
<span class="w"> </span><base>D:/ms4w/tmp/ms_tmp/cache</base>
<span class="w"> </span><!--<symlink_blank/>-->
</cache>
</pre></div>
</div>
</li>
<li><p>Finally, restart your Apache. You should see a message in Apache’s error.log with a message
similar to:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="o">[</span>notice<span class="o">]</span><span class="w"> </span>Apache/2.2.21<span class="w"> </span><span class="o">(</span>Win32<span class="o">)</span><span class="w"> </span>mod-mapcache/0.5-dev<span class="w"> </span>configured<span class="w"> </span>--<span class="w"> </span>resuming<span class="w"> </span>normal<span class="w"> </span>operations
</pre></div>
</div>
</li>
</ul>
</section>
<section id="test-your-mapcache-module">
<h3><a class="toc-backref" href="#table-of-contents" role="doc-backlink">Test Your MapCache Module</a><a class="headerlink" href="#test-your-mapcache-module" title="Link to this heading">¶</a></h3>
<ul>
<li><p>In your web browser, visit the local MapCache demo page: <a class="reference external" href="http://127.0.0.1/mapcache/demo/">http://127.0.0.1/mapcache/demo/</a>. You should see
a clickable list of demo links:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">tms</span>
<span class="n">wmts</span>
<span class="n">gmaps</span>
<span class="n">kml</span>
<span class="n">ve</span>
<span class="n">wms</span>
</pre></div>
</div>
</li>
<li><p>Click on one of the demos (such as <a class="reference external" href="http://127.0.0.1/mapcache/demo/wmts">http://127.0.0.1/mapcache/demo/wmts</a>). A map viewer should load, similar
to the image below.</p>
<img alt="../_images/mapcache-demo.jpg" class="no-scaled-link" src="../_images/mapcache-demo.jpg" style="width: 900px; height: 600px;" />
</li>
<li><p>Zoom in a few times. Your configured cache location should be generating tiles (in this case inside
D:/ms4w/tmp/ms_tmp/cache/).</p>
<img alt="../_images/mapcache-disk.jpg" src="../_images/mapcache-disk.jpg" />
</li>
</ul>
</section>
</section>
</section>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="Main">
<div class="sphinxsidebarwrapper">
<search id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</search>
<script>document.getElementById('searchbox').style.display = "block"</script><h3>Navigation</h3>
<p>
<a href="../about.html" title="About">About</a><br>
<a href="../products.html" title="Products">Products</a><br>
<a href="../community/index.html" title="Community">Community</a><br>
<a href="../development/index.html" title="Development">Development</a><br>
<a href="../download.html" title="Downloads">Downloads</a><br>
<a href="../documentation.html" title="Documentation">Documentation</a><br>
<a href="../faq.html" title="FAQ">FAQ</a><br>
<a href="../psc.html" title="PSC">PSC</a><br>
<a href="https://fosstodon.org/@mapserver" title="Mastodon">Mastodon</a>
</p>
<h3>Current Table Of Contents</h3>
<ul>
<li><a class="reference internal" href="#">Compilation & Installation</a><ul>
<li><a class="reference internal" href="#getting-the-source">Getting the Source</a></li>
<li><a class="reference internal" href="#linux-instructions">Linux Instructions</a><ul>
<li><a class="reference internal" href="#apache-module-specific-instructions">Apache Module Specific Instructions</a></li>
<li><a class="reference internal" href="#nginx-specific-instructions">nginx Specific Instructions</a></li>
<li><a class="reference internal" href="#cgi-fastcgi-specific-instructions">CGI/FastCGI Specific Instructions</a><ul>
<li><a class="reference internal" href="#apache-with-mod-cgi">Apache with mod_cgi</a></li>
<li><a class="reference internal" href="#iis-and-fastcgi">IIS and FastCGI</a></li>
</ul>
</li>
<li><a class="reference internal" href="#customizing-the-build-or-if-something-went-wrong">Customizing the Build, Or If Something Went Wrong</a><ul>
<li><a class="reference internal" href="#options-supported-by-the-mapcache-cmake-builder">Options Supported By the MapCache CMake Builder</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#windows-instructions">Windows Instructions</a><ul>
<li><a class="reference internal" href="#dependencies">Dependencies</a></li>
<li><a class="reference internal" href="#configure-your-makefile">Configure Your Makefile</a></li>
<li><a class="reference internal" href="#compilation">Compilation</a></li>
<li><a class="reference internal" href="#move-the-module-into-the-apache-directory">Move the Module Into the Apache Directory</a></li>
<li><a class="reference internal" href="#configure-your-installed-apache">Configure Your Installed Apache</a></li>
<li><a class="reference internal" href="#test-your-mapcache-module">Test Your MapCache Module</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="Related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="config.html" title="Configuration File"
>next</a> |</li>
<li class="right" >
<a href="index.html" title="MapCache 1.16.0"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Home</a> »</li>
<li class="nav-item nav-item-1"><a href="../documentation.html" >MapServer 8.6.3 Documentation</a> »</li>
<li class="nav-item nav-item-2"><a href="index.html" >MapCache 1.16.0</a> »</li>
<li class="nav-item nav-item-this"><a href="">Compilation & Installation</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
© <a href="../copyright.html">Copyright</a> 2026, Open Source Geospatial Foundation.
Last updated on 2026-05-16.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 9.1.0.
</div>
</body>
</html>