GitHub - naviserver-project/naviserver: NaviServer is a scalable, multithreaded web server / multi-protocol server written in C and Tcl. It can be easily extended in either language to create interesting web sites and services.

6 min read Original article ↗

WHAT IS THIS?

This is the source distribution of NaviServer, a versatile multiprotocol (HTTP(S), etc.) server written in C/Tcl. It is designed to be easily extended in either language, allowing you to build innovative and scalable websites and services.

Contents

  1. Introduction
  2. Documentation
  3. Versioning and Release Policy
  4. Compiling and Installing
  5. Install NSF/XOTcl
  6. Mailing Lists

1. Introduction

NaviServer is maintained, enhanced, and distributed freely by the open source community. Download NaviServer or browse its bug/patch database on the SourceForge site.

The source code is hosted on GitHub and additional information can be found on the Tcl Wiki.

NaviServer is released as free and open source software. For full licensing details, please refer to the license.terms file included in this distribution.

2. Documentation

Documentation is located in the doc subdirectory. Although it is still a work in progress, it will eventually be available in both Unix nroff format (ideal for viewing with the man command) and HTML format (compatible with any modern web browser).

The latest development documentation is available online at:
https://naviserver.sourceforge.io/n/toc.html

3. Versioning and Release Policy

NaviServer uses a three-digit version scheme:

  • MAJOR.MINOR.PATCH (for example, 5.0.1)
  • The PATCH level is strictly for fixes — no new functionality or behavior changes.
  • New features and API changes appear only in MINOR or MAJOR releases.

Active Branches

  • release/4.99 - legacy maintenance
  • release/5.0 - current stable line
  • main - active development

Tagging

  • Each release is marked by an annotated Git tag in the form
    naviserver-MAJOR.MINOR.PATCH, for example:

    git checkout release/5.0
# ...
git tag -a naviserver-5.0.1 -m naviserver-5.0.1
git push --follow-tags

    Tags always correspond to versions in a release/* branch.

Development work happens on main; bug fixes may be cherry-picked into the relevant release/* branch before tagging.

4. Compiling and Installing

NaviServer compiles and runs on various platforms, including FreeBSD, Linux, Solaris, macOS 10.2+, and Windows.

An install script for Unix platforms (including macOS) with extensive configuration options is available from:
https://github.com/gustafn/install-ns

This script installs NaviServer with optionally extra NaviServer modules, it support different compile options such as choice the the malloc library, etc.

The following sections describe, in detail, how to compile and install NaviServer along with NSF.

4a. Download, Configure, Build and Install Tcl 8.5 or Better

If you already have Tcl installed and it was built with threads enabled, you can use it. Otherwise, download the latest Tcl release from tcl-lang.org and follow the included README instructions. You may install Tcl in the same directory where you plan to install NaviServer (e.g., /usr/local/ns, recommended to avoid version mismatches) or in a separate location.

Note: NaviServer 4.99.* requires Tcl 8.5 or Tcl 8.6, while NaviServer 5 support Tcl 9.

On a Unix-like system, run:

gunzip < tcl8.6.17-src.tar.gz | tar xvf -
cd tcl8.6.17/unix
./configure --prefix=/usr/local/ns --enable-threads --enable-symbols
make install

4b. Install GNU Make

The NaviServer makefiles require GNU Make. Verify your installation with:

If necessary, install GNU Make from gnu.org or get if via the package manager of your operating system.

4c. Download, Configure, Build, and Install NaviServer

One has two options to obtain the NaviServer source code: you can either download tar releases from SourceForge, or obtain the sources from GitHub:

Tar releases:
https://sourceforge.net/projects/naviserver/files/

Latest development source code (Git repository):
https://github.com/naviserver-project/naviserver/

Compile from Tar Releases

To compile from a tar releases, execute:

gunzip < naviserver-5.0.0.tar.gz | tar xvf -
cd naviserver-5.0.0
./configure --prefix=/usr/local/ns --with-tcl=/usr/local/ns/lib --enable-symbols
make
su -c 'make install'

Configure Script Options:

  • --with-tcl=/usr/local/ns/lib
    Locate tclConfig.sh in the specified directory.

  • --with-zlib=/usr
    Specify the location of the zlib headers (e.g., install via yum install zlib-devel on Fedora).

  • --enable-symbols
    Build with debug symbols enabled (recommended).

  • --prefix=/usr/local/ns
    Set the installation directory for programs, man pages, and runtime files. If you compile Tcl, use also for Tcl the same --prefix location.

To compile with the Purify tool, run:

make PURIFY="purify -cache-dir=/home/joe/my-cache-dir" install

See make help for the provided options for testing etc.

Compile from Versions from GitHub

If you clone NaviServer from the GitHub repository, run ./autogen.sh with the configure options (instead of ./configure) to generate the makefiles. You will need recent versions of autoconf, automake, and the dtplite package from tcllib to build the documentation.

Tip: Use make build-doc to generate documentation; otherwise, make install may complain.

The other steps are identical to compilation from tar releases.

4d. Create and Edit a NaviServer Configuration File

By convention, NaviServer uses a configuration file named nsd.tcl.

cd /usr/local/ns
cp sample-config.tcl nsd.tcl
vi nsd.tcl

Sample files are provided:

  • nsd-config.tcl Simple configuration file, suitable for simple applications
  • sample-config.tcl includes every configuration option and its default value (remove unused options).
  • openacs-config.tcl NaviServer configuration file for OpenACS

Find the documentation for configuring NaviServer in admin-config.

4e. Run the Server in a Shell

Test NaviServer by running:

cd /usr/local/ns
./bin/nsd -f -t conf/nsd.tcl

The -f option runs the server in the foreground with important log messages directed to your terminal.

4f. Install Additional Modules

For tarball releases, compatible modules are provided via SourceForge. For example, to install a module named nsfoo:

gunzip < naviserver-5.0.0-modules.tar.gz | tar xvf -
cd modules/nsfoo
make install NAVISERVER=/usr/local/ns

Alternatively, clone modules from GitHub:

git clone https://github.com/naviserver-project/nsfoo.git
cd nsfoo
make install NAVISERVER=/usr/local/ns

For a complete list of modules, visit GitHub repositories.

4g. Compile for Windows with Msys + Mingw

Download the minimal environment from https://sourceforge.net/projects/mingw/files/.

  1. Download the minimal Msys + Mingw environment from SourceForge.

  2. Extract the zip file and follow the instructions in README.TXT to launch the msys shell.

  3. In the msys shell, run:

    cd /c/naviserver-5.0.0
./configure --prefix=c:/naviserver --with-tcl=c:/naviserver/lib
make install

Note: This example assumes Tcl is built with Mingw using the prefix c:/naviserver.

4h. Compile for Windows with MSVC

Update the tcl_64 and tcllib_64 variables in Makefile.win32 (in the NaviServer root directory) and check settings in include/Makefile.win32 (such as HAVE_OPENSSL_EVP_H and openssl_64).

Run the appropriate Microsoft build environment script, for example:

  • "C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvars64.bat"
  • "%ProgramFiles%\Microsoft SDKs\Windows\v7.1\Bin\SetEnv.Cmd" /Debug /x64 /win7

Then execute:

4i. Cross-Compiling for Windows 64-bit (using gcc/mingw)

Some Mingw settings may not be auto-detected. Specify them explicitly:

./configure --host=x86_64-w64-mingw32 --enable-64-bit \
      --prefix=<path> --with-zlib=<path> --with-openssl=<path> --with-tcl=<path>/lib

CFLAGS="-DHAVE_INET_PTON -DHAVE_INET_NTON -DHAVE_GETADDRINFO -D_WIN32_WINNT=0x600" \
      LDFLAGS="-static-libgcc" \
      make LIBLIBS="-Wl,-Bstatic -lpthread -Wl,-Bdynamic"

Since the installation script does not expect the .exe extension, copy the executables without the extension as a workaround:

cp nsthread/nsthreadtest.exe nsthread/nsthreadtest
cp nsd/nsd.exe nsd/nsd
cp nsproxy/nsproxy.exe nsproxy/nsproxy
make install

4j. (Optional) To Compile for Windows with Cygwin

(Instructions for compiling with Cygwin will be provided if available.)

5. Install NSF/XOTcl

NSF/XOTcl provides essential functions (e.g., cryptographic and reverse proxy capabilities) that enhance NaviServer’s features. Although optional for users of Tcl 8.5, these components are recommended for all installations.

Download NSF/XOTcl from either SourceForge or GitHub, and install it into the NaviServer source tree using the same --prefix as NaviServer:

git clone https://github.com/nm-wu/nsf
cd nsf
./configure --prefix=/usr/local/ns
make
sudo make install

6. Mailing Lists

Join the NaviServer mailing lists to discuss user questions, configuration, development, and future directions. Visit:
https://sourceforge.net/p/naviserver/mailman/

Thank you for your interest in NaviServer. We hope you find it valuable and look forward to your contributions on our mailing lists.