Skip to content

Windows Installation with IIS

Jump to bottom
Ryan Hodges edited this page Jun 14, 2022 · 4 revisions

Installing on Windows is a bit more difficult than on Linux, but can be done. Serving via IIS is theoretically possible, and will be tested during the creation of this document. This tool works best in Linux, and using an Ubuntu server is the preferred method. If that is not an option, perhaps WSL2 is an option, but will not be explored in this document.

Also note that certain features are NOT supported in a Windows installation, namely: accessing the PostgreSQL+PostGIS database from GIS software.

Installing The Django Application and DB on Windows

Installing Pre-Requisites:

  • A Windows Server (Tested on Windows Server 2019 and 2022)
  • A text editor
  • An internet connection
  • A modern browser (Edge, Chrome, or Firefox, but NOT Internet Explorer)
  • Python 3.10+
    • Download and run the latest Windows installable .exe
    • Add Python 3.x to PATH
    • When asked, disable 'path length limit' (expand the default character limit on PATH)
  • Git
  • PostgreSQL + PostGIS
    • Download the latest VERSION 12 (not 14 or higher)
    • Install all components
      • Keep track of your password for user postgres
      • Keep the default port: 5432 (you may change this for additional security, but this document assumes this port)
    • Run "Stack Builder" to install PostGIS
      • Select your new PostgreSQL v12 server for the target
      • Expand options under 'Spatial Extensions' and check "PostGIS 3.2 Bundle"
      • Accept all default options and agree to the GPL license
        • Accept proposed changes to your Environment Variables
  • OSGeo4W + GDAL
    • Download and run the installer
    • Select 'Express Install'
    • Select your mirror
    • Select GDAL

Install the Application

Download Source Code

This document assumes you will store the source code in a directory called C:/Apps/. If you wish to install in Program Files or another location, you will need to track your own changes throughout this document.

Downloading the source can be done using two methods:

  • Git Bash (if you're comfortable with the command line) 
    cd /c/
mkdir Apps
cd /c/Apps
git clone https://github.com/Ecotrust/TEKDB.git
  • Git GUI

Prepare your environment

  • Modify your OS Environment Variables from the command prompt
    • This is scripted in the file C:\Apps\TEKDB\scripts\Windows\set_osgeo_environment.bat
    • If you installed OSGeo4W to anywhere other than C:\OSGeo4W, update the first line of that script to reflect your new location
    • run C:\Apps\TEKDB\scripts\Windows\set_osgeo_environment.bat
  • Django + Environment
    • cd to your application location: cd C:\Apps\TEKDB
    • Create a virtual environment
      • py -m venv env
      • py -m pip install --upgrade pip
    • Activate your virtual environment
      • env\Scripts\activate.bat
    • Install requirements
      • pip install -r TEKDB\requirements.txt

Configuration

Configure Local Settings (Text Editor, File Manager)

  • Copy C:\Apps\TEKDB\TEKDB\TEKDB\local_settings.py.template to C:\Apps\TEKDB\TEKDB\TEKDB\local_settings.py
  • Edit C:\Apps\TEKDB\TEKDB\TEKDB\local_settings.py so that it contains the following lines: 
    ALLOWED_HOSTS = [
    'YOUR_URL',
    'localhost',
]
DATABASES = {
    'default': {
        'ENGINE': 'django.contrib.gis.db.backends.postgis',
        'NAME': 'tekdb',
        'USER': 'postgres',
        'PASSWORD': 'YOUR_POSTGRES_PASSWORD',
        'HOST': 'localhost',
        'PORT': '5432',
    }
}

GEOS_LIBRARY_PATH=r'C:\OSGeo4W\bin\geos_c'
GDAL_LIBRARY_PATH=r'C:\Program Files\PostgreSQL\12\bin\libgdal-29'
MEDIA_ROOT=r'C:\Apps\TEKDB\TEKDB\media'
STATIC_ROOT=r'C:\Apps\TEKDB\TEKDB\static'
DEBUG=True
  • Be sure to update the following fields:
    • ALLOWED_HOSTS: replace this list of strings with your own intended URL(s) and/or IP Address
      • A browser navigating to any address not in this list will not see the application
    • DATABASES:
      • NAME: If you wish to use a different DB name you will gain very little security (through obscurity, only) but will likely have to adjust other steps in this document
      • USER: Like name, you'll gain a little more security, but only if you expose your PostgreSQL port.
      • PASSWORD: This value should match the password you created when installing PostgreSQL above
        • This will need to be wrapped in single-quotes, even if your password is numeric

Create the Database

You will create a database owned by the default 'postgres' user.

If you need additional security on your server, you can create a new PostgreSQL database user and make them the owner, updating your setting/configuration above and altering the steps below to match your username/password. You may also need to update additional PostgreSQL configuration files. This is beyond the scope of this document. It is recommended that if you need this level of security you proceed with the Linux installation.

This can be done in 2 ways, with a GUI or with the Command Prompt. We recommend the Command Prompt method.

  • Command Prompt: 
    psql -U postgres
CREATE DATABASE tekdb;
\q
  • GUI/pgAdmin4:
    • Open pgAdmin4
    • Create a 'master password'
    • Log in providing the 'postgres' password created when installing PostgreSQL
    • Expand 'Servers' -> 'PostgreSQL 12'
    • Right click on 'Databases'
    • Click on 'Create -> Database…'
    • image
    • Name it 'tekdb' and save

Final Database setup and Testing

  • Open a command prompt
  • Be sure you've activated your Python Virtual environment
    • If so, you should see (env) before your prompt on each line
  • run: 
    cd C:\Apps\TEKDB\TEKDB\
py manage.py migrate
    • When done, you should see "Running migrations:" followed by a list of a few dozen lines reading something like "Applying xxx… OK"
    • If you DO NOT see this, or get an error, double check that you created your database correctly, and that your local_settings.py file has DATABASES filled out correctly (case matters!)
  • run: 
    py manage.py test TEKDB
    • All tests should pass. If not, please reach out to the development team or open a ticket in GitHub
  • run: 
    py manage.py loaddata TEKDB\fixtures\default_empty_database.json
  • Ensure the DEBUG=True line is still in your local_settings.py file team or open a ticket in GitHub
  • run: 
    py manage.py runserver
    • Open http://localhost:8000/ in a browser
    • You should see the project homepage
      • If not, review the installation steps, and if you can't debug, reach out to the development team or open a ticket in GitHub

Serve the Application

Install IIS

This can be done 2 ways: via GUI or Command Prompt. The GUI method is harder, but better tested and therefore recommended. GUI:

  • Click on Windows Logo ('Start')
  • Select 'Server Manager' under 'Windows Server'
  • Click on "2: Add Roles and Features"
  • Next
  • Next ('Role-based or feature-based installation' is selected)
  • Next (Your sever is already selected from the pool)
  • Under 'Roles' check the "Web Server (IIS)" box
    • Click the 'Add Features' button in the pop-up
  • Next
  • Next (Features)
  • Next (Web Server Role (IIS))
  • Under 'Web Server' find and expand 'Application Development'
    • Select 'CGI'
  • Next
  • Install (Confirmation)

Command Prompt/PowerShell

  • Open PowerShell
  • Run: 
    Install-WindowsFeature -Name Web-Server, Web-CGI -IncludeManagementTools

Install and Configure FastCGI

NOTE: This should be done BOTH within your Python Virtual Environment AND outside to fit the following instructions and work

In your py env:

pip install wfastcgi

Outside of your py env (deactivate)

py -m pip install wfastcgi

While doing our best to capture the essential steps below, a more detailed, and fully-illustrated write-up is available from Sagar Gadewar on medium.com.

  • Open IIS
  • Double-click to open 'FastCGI Settings'
  • Click on 'Add Application'
    • Full Path: C:\Apps\TEKDB\env\Scripts\python.exe
    • Arguments: C:\Apps\TEKDB\env\Lib\site-packages\wfastcgi.py
    • EnvironmentVariables:
      • 0
        • Name:
          • DJANGO_SETTINGS_MODULE
        • Value:
          • TEKDB.settings
      • 1
        • Name:
          • PYTHONPATH
        • Value:
          • C:\Apps\TEKDB\TEKDB
      • 2
        • Name
          • WSGI_HANDLER
        • Value:
          • TEKDB.wsgi.application

Create IIS Web Site Record

The settings below assume that you are not serving other applications on this server. If you are, then you will definitely need to consider whether the values below for IP Address below when editing bindings will serve your needs. Hopefully you have someone savvy with IIS on staff in this case.

  • Open IIS
  • In left panel, under your server, right-click on 'Sites' and select 'Add Site'
    • Site name: TEKDB
    • Physical path: C:\Apps\TEKDB\TEKDB
    • Binding
      • IP address:
      • Port: 80
      • Host name:
  • Under 'Sites' right-click on 'TEKDB'
    • Select 'Edit Bindings'
    • Click 'Add…'
      • Type: http
      • IP address: 127.0.0.1.
      • Port: 80
    • Click 'Add…' (again)
      • Type: http
      • IP address: 'All Unassigned'
      • Port: 80
    • Click 'Add…' (again)
      • Type: http
      • IP address:
      • Port: 80
  • Under 'Sites' right-click on 'Default Web Site' and under 'Manage Web Site' click on 'Stop'
  • Click on your TEKDB site
  • Double click on 'Handler Mappings'
  • Click on 'Add Module Mapping…'
    • Fields:
      • Request path: *
      • Module: FastCgiModule
      • Executable: C:\Apps\TEKDB\env\Scripts\python.exe|C:\Apps\TEKDB\env\Lib\site-packages\wfastcgi.py
      • Name: Django Handler
    • Click on 'Request Restrictions…'
      • UNCheck the "Invoke handler only if request is mapped to:" box
      • Click OK
    • Click OK

Enable your application pool to run Python

  • If you didn't install python to a custom location, it will go under your user's AppData directory:
    • C:\Users\YOUR_USER\AppData\Local\Programs\Python\Python310
  • Navigate a file browser to …AppData\local\Programs\Python
  • Right-click on Python310 (or Python3X, depending on your Python Version)
  • Select 'Properties'
  • Click on the 'Security' tab at the top
  • Click on the 'Edit…' button to change permissions
  • Under the 'Group or user names:' section click on the 'Add…' button
  • Ensure
    • 'Select this object type' includes 'Users' and 'Groups'
    • 'From this location' has your server's name
  • For 'Enter the object names to select' insert:
    • IIS AppPool\TEKDB
  • Click 'Check Names' button to ensure that you've selected a real record
  • Click 'OK'
  • Select TEKDB from 'Group or user names'
  • Under 'Permissions for TEKDB' check Full Control's 'Allow' box
    • This should check all 'Allow' boxes below
  • Click the 'Apply' button
    • Wait a moment while permissions are updated recursively down the directory
  • Click 'OK'

Static and Media Files

"Collect" Static Files (Command Prompt)

  • be sure your virtual environment is activated 
    cd C:\Apps\TEKDB\TEKDB
py manage.py collectstatic
    • type 'yes' if/when asked to

Support Static Files (IIS)

  • under Sites, right-click on TEKDB
    • Select 'Add Virtual Directory'
      • Alias:
        • static
      • Physical path:
        • C:\Apps\TEKDB\TEKDB\static
      • Expand the TEKDB site to see the 'static' folder with the alias icon
      • Click on the 'static' folder
      • Double click on 'Handler Mappings'
      • To the right, select 'View Ordered List…'
      • Click on the 'StaticFile' record
      • Click 'Move Up' to the right until 'StaticFile' is at the top

Support Media Files (IIS)

  • Be sure to have already run py manage.py collectstatic above
  • In IIS, under Sites, right-click on TEKDB
    • Select 'Add Virtual Directory
      • Alias:
        • media
      • Physical path:
        • C:\Apps\TEKDB\TEKDB\media
    • Expand the TEKDB site to see the 'media' folder with the alias icon
    • Click on the 'media' folder
    • Double click on 'Handler Mappings'
    • To the right, select 'View Ordered List…'
    • Click on the 'StaticFile' record
    • Click 'Move Up' to the right until 'StaticFile' is at the top

If you are serving on port 80 (default) then you are done. You should see your site at either the URL you configured (if your DNS is also configured similarly) or at: http://127.0.0.1/

Optional Additional Configuration

Other Ports: Windows Defender Firewall

If serving on a port other than 80:

  • Specifics of Firewalls are beyond the scope of this document.
  • To access the website (by default) Port 80 will need to allow inbound connections
    • This is done by default
  • To access the PostgreSQL Database (particularly for GIS data) you need to expose Port 5432

Accessing GIS data from ArcGIS

Experimental: This is not fully supported, but should work in theory. Connecting on the server itself should be allowed by default.

Connecting from a remote computer using ArcGIS or QGIS will require:

  • Exposing port 5432 (or whatever port you are serving PostgreSQL on)
    • See above section on 'Other Ports'
  • updating the configuration file pg_hba.conf.
    • This is located at C:\Program Files\PostgreSQL\12\data\pg_hba.conf
    • add a line near the bottom like: 
      host    tekdb    postgres    YOUR_IP_ADDRESS        md5
    • Once you save your edits to the config file, you need to restart PostgreSQL:
      • Click on the Windows button ('start')
      • Find and expand 'PostgreSQL 12
      • Click on 'Reload Configuration'
      • A command prompt will open. You can press 'Enter' when told to close it.
    • Connecting ArcGIS is covered in the documentation:
Clone this wiki locally