Installation & Deployment

From first run to production architecture: everything you need to launch AxonASP with confidence.

📋 Table of Contents

Prerequisites
Deployment Modes
Quick Start
Build & Cross-Compile
FastCGI Mode
Configuration (.env)
Reverse Proxy
IIS Compatibility & web.config
Multiple Instances
Debug & Troubleshooting
Production Checklist

Prerequisites

Go 1.25+
Git for cloning the repository
Basic Classic ASP / VBScript understanding

Good news: AxonASP is a single-binary runtime with simple operational flow.

Deployment Modes

Standalone (`axonasp.exe`)

Best for development and simple deployments. Built-in HTTP server on port 4050 by default.

FastCGI (`axonaspcgi.exe`)

Best for production and high-traffic stacks with nginx/Apache/IIS integration.

Quick Start

git clone https://github.com/guimaraeslucas/axonasp.git
cd axonasp
go mod download
go run main.go

Open http://localhost:4050.

Linux Installer (RPM distro + nginx proxy)

wget https://raw.githubusercontent.com/guimaraeslucas/axonasp/main/linux_install.sh -O linux_install.sh && sed -i 's/\r$//' linux_install.sh && chmod +x linux_install.sh && bash linux_install.sh

Build & Cross-Compile

go build
# Windows full build helper
./build.ps1

Cross-platform

# Windows
GOOS=windows GOARCH=amd64 go build

# Linux
GOOS=linux GOARCH=amd64 go build

# macOS Intel
GOOS=darwin GOARCH=amd64 go build

# macOS Apple Silicon
GOOS=darwin GOARCH=arm64 go build

FastCGI Mode

go build -o axonaspcgi.exe ./axonaspcgi
./axonaspcgi -listen :9000 -root ./www
# Unix socket example
./axonaspcgi -listen unix:/var/run/axonasp.sock -root /var/www/asp

Native integration with nginx, Apache, IIS
Great fit for production-grade SSL, cache, and static handling
Strong scaling model for high-traffic environments

Open complete FastCGI guide

Configuration (.env)

SERVER_PORT=4050
WEB_ROOT=./www
TIMEZONE=America/Sao_Paulo
DEFAULT_PAGE=index.asp,default.asp
SCRIPT_TIMEOUT=30
DEBUG_ASP=FALSE

Variable	Default	Description
`SERVER_PORT`	4050	HTTP server port
`WEB_ROOT`	./www	Root directory for ASP files
`TIMEZONE`	America/Sao_Paulo	Server timezone
`DEFAULT_PAGE`	index.asp,default.asp,...	Default page hierarchy
`SCRIPT_TIMEOUT`	30	Script timeout (seconds)
`DEBUG_ASP`	FALSE	Detailed ASP stack traces
`CLEAN_SESSIONS`	TRUE	Cleanup expired sessions at startup
`ASP_CACHE_TYPE`	disk	AST cache type (memory/disk)
`ASP_CACHE_TTL_MINUTES`	0	AST cache TTL
`AXONASP_VM`	FALSE	Experimental VM toggle
`VM_CACHE_TYPE`	disk	VM cache type
`VM_CACHE_TTL_MINUTES`	0	VM cache TTL
`MEMORY_LIMIT_MB`	0	Process memory limit
`ERROR_404_MODE`	DEFAULT	DEFAULT or IIS mode
`BLOCKED_EXTENSIONS`	see .env	Blocked extension list
`COM_PROVIDER`	auto	Access COM provider strategy
`SQL_TRACE`	FALSE	Verbose SQL logs
`SMTP_*`	-	SMTP configuration
`MYSQL_HOST`	localhost	G3DB MySQL host
`POSTGRES_HOST`	localhost	G3DB PostgreSQL host
`MSSQL_HOST`	localhost	G3DB SQL Server host
`SQLITE_PATH`	./database.db	G3DB SQLite path

Reverse Proxy

Nginx

server {
    listen 80;
    server_name example.com;
    root /var/www/asp;

    location ~ \.(asp|aspx)$ {
        fastcgi_pass   127.0.0.1:9000;
        include        fastcgi_params;
        fastcgi_param  SCRIPT_FILENAME  $document_root$fastcgi_script_name;
    }
}

Apache

<VirtualHost *:80>
    ServerName app1.example.com
    ProxyPreserveHost On
    ProxyPass / http://localhost:4050/
    ProxyPassReverse / http://localhost:4050/
</VirtualHost>

IIS (URL Rewrite + ARR)

<configuration>
  <system.webServer>
    <rewrite>
      <rules>
        <rule name="ReverseProxyToAxonASP" stopProcessing="true">
          <match url="(.*)" />
          <action type="Rewrite" url="http://localhost:4050/{R:1}" />
        </rule>
      </rules>
    </rewrite>
  </system.webServer>
</configuration>

IIS Compatibility & web.config

AxonASP reads web.config for IIS-style rewrite rules and custom error handling.

404 Modes

default: static errorpages/404.html
asp: custom ASP page via CUSTOM_404_PAGE
iis: httpErrors in web.config

Rewrite Example

<rule name="Product Page" stopProcessing="true">
  <match url="^product/([0-9]+)$" />
  <action type="Rewrite" url="/product.asp?id={R:1}" />
</rule>

Multiple Instances

One application per instance (global.asa model). Run multiple instances for multiple apps:

# App 1
SERVER_PORT=4050 WEB_ROOT=./app1/www ./axonasp

# App 2
SERVER_PORT=4051 WEB_ROOT=./app2/www ./axonasp

# App 3
SERVER_PORT=4052 WEB_ROOT=./app3/www ./axonasp

Debug & Troubleshooting

DEBUG_ASP=TRUE
SQL_TRACE=TRUE

Port conflict: change SERVER_PORT.
No stack traces: set DEBUG_ASP=TRUE.
Database failures: validate drivers and connection strings.
Session persistence issues: ensure temp/session exists and is writable.

Production Checklist

Run FastCGI behind nginx/Apache/IIS.
Set DEBUG_ASP=FALSE.
Use HTTPS termination at reverse proxy.
Define memory and cache strategy for your workload.
Monitor logs and keep dependencies updated.

Launch-ready: with AxonASP you keep classic compatibility and gain modern deployment power immediately.

Open Complete Documentation Back to Home