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.

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

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.

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

NaviServer uses a three-digit version scheme:

• MAJOR.MINOR.PATCH (for example, 5.1.0)
• 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 - maintenance
• release/5.1 - 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.1
  # ...
  git tag -a naviserver-5.1.0 -m naviserver-5.1.0
  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.

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.

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 supports additionally Tcl 9.

On a Unix-like system, run:

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

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

make -v

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

There are two common ways to obtain the NaviServer sources:

SourceForge release files: https://sourceforge.net/projects/naviserver/files/

GitHub repository and release archives: https://github.com/naviserver-project/naviserver/

The two distributions differ in important ways:

• The SourceForge release tarballs are generated by make dist. They include the generated configure script and generated build files, and can be configured directly with ./configure.

• The GitHub repository checkout and the automatically generated GitHub source archives contain the bare source tree. They do not contain all generated files. When building from GitHub sources, run ./autogen.sh instead of ./configure.

• The SourceForge release directory traditionally contains the NaviServer core release together with matching NaviServer module releases from other repositories in the naviserver-project organization. The GitHub release/source archive for the naviserver repository contains only the NaviServer core sources.

To compile from a SourceForge release tarball, execute:

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

The same pattern applies to NaviServer modules downloaded from the matching SourceForge release directory. Build and install NaviServer first, then build the required modules against the installed NaviServer tree.

When building from a GitHub checkout or from a GitHub-generated source archive, use ./autogen.sh to generate configure and the makefiles:

git clone https://github.com/naviserver-project/naviserver.git
cd naviserver
./autogen.sh --prefix=/usr/local/ns --with-tcl=/usr/local/ns/lib --enable-symbols
make
su -c 'make install'

To build a specific released version from GitHub, check out the corresponding tag before running ./autogen.sh:

git clone https://github.com/naviserver-project/naviserver.git
cd naviserver
git checkout naviserver-5.1.0
./autogen.sh --prefix=/usr/local/ns --with-tcl=/usr/local/ns/lib --enable-symbols
make
su -c 'make install'

Building from GitHub sources requires recent versions of autoconf and automake. For generating the documentation, the dtplite package from tcllib is required.

Tip: Use make build-doc to generate documentation; otherwise, make install may complain when generated documentation files are missing.

The automatically generated GitHub source archives, such as "Source code (tar.gz)" and "Source code (zip)" on the GitHub release page, are snapshots of the repository contents. They are not equivalent to the SourceForge make dist tarballs.

The following options are commonly used with either ./configure from a SourceForge release tarball or ./autogen.sh from GitHub sources:

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

• --with-zlib=/usr Specify the location of the zlib headers, for example when zlib is installed via a distribution package such as zlib-devel on Fedora.

• --enable-symbols Build with debug symbols enabled. This is recommended.

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

• --with-openssl[=DIR|INCLUDEDIR,LIBDIR]

  Enable OpenSSL support and specify how to locate headers and libraries. Requires OpenSSL 1.1.1 or newer, or LibreSSL 4.1.0 or newer. Provider-based crypto features require OpenSSL 3.0 or newer; individual features may require later versions. HTTP/3 requires OpenSSL 4.0.2 or newer and a compatible nghttp3 library.

  The option supports three forms:

  • --with-openssl Use OpenSSL via pkg-config, if available, or fall back to system defaults.

  • --with-openssl=/path/to/openssl Use an OpenSSL installation prefix. The build system will use headers from /path/to/openssl/include and libraries from /path/to/openssl/lib or /path/to/openssl/lib64.

    When possible, absolute library paths, for example libssl.so and libcrypto.so, are used to avoid accidentally linking against unrelated libraries found via earlier -L flags.

  • --with-openssl=/path/to/include,/path/to/lib Specify include and library directories explicitly. This is useful for non-standard installations or staged builds where headers and libraries are located in different directories.

  If this option is provided explicitly and the specified directories are invalid or OpenSSL cannot be detected, configuration will fail.

For a detailed list of all options, use:

./configure --help

or, when building from GitHub sources (using the configure options as arguments).

./autogen.sh --help

To see themost important make optioms, run:

make help

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.

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.

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

gunzip < naviserver-5.1.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.

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.1.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.

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:

nmake -f Makefile.win32

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

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

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

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.