Skip to content
Klutch.sh Docs

Deploying an AWStats App

Introduction

AWStats is a powerful, open-source web analytics and log analyzer that generates advanced statistics about web, streaming, mail, and FTP servers. By parsing server log files, AWStats produces detailed visual reports on traffic, visitor behavior, search engine referrals, bandwidth usage, and more, making it an excellent choice for self-hosted analytics.

Deploying AWStats on Klutch.sh with a Dockerfile lets you run a fully managed analytics dashboard in the cloud while keeping control of your data and logs. This guide covers everything from creating a Docker-based AWStats setup to configuring persistent volumes and deploying it through the Klutch.sh dashboard at klutch.sh/app.

Prerequisites

Before you begin, ensure you have:

  • A Klutch.sh account
  • A GitHub account (GitHub is the only supported git source)
  • Docker installed locally (optional but recommended for testing)
  • Basic familiarity with Apache or Nginx access logs
  • Some comfort with editing configuration files

Project Setup for AWStats

1. Create a Project Directory

Create a dedicated directory for your AWStats deployment:

Terminal window
mkdir awstats-klutch
cd awstats-klutch
git init

2. Sample Directory Structure

You can keep your project simple with the following structure:

awstats-klutch/
  Dockerfile
  awstats.conf
  webserver.conf        # Optional: VirtualHost/server block config snippet
  sample-logs/
    access.log          # Example log file for local testing

AWStats Configuration Basics

AWStats is configured via a text configuration file (usually named awstats.yourdomain.conf). For a simple deployment, you can start with a single config file that analyzes combined Apache or Nginx access logs.

Example awstats.conf

Create awstats.conf in your project directory:

# AWStats basic configuration for Klutch.sh deployment


LogFile="/var/log/apache2/access.log"
LogType=W
LogFormat=1
SiteDomain="example-app.klutch.sh"
HostAliases="example-app.klutch.sh 127.0.0.1 localhost"
DNSLookup=1


DirData="/var/lib/awstats"
DirCgi="/usr/lib/cgi-bin"
DirIcons="/usr/share/awstats/icon"


AllowFullYearView=3


# Security: limit who can access the AWStats interface (adjust for your use case)
AllowAccessFromWebToFollowingIPAddresses="all"

This configuration:

  • Tells AWStats where to find the log file (/var/log/apache2/access.log)
  • Sets the main domain to example-app.klutch.sh (update this after deployment)
  • Stores AWStats data files in /var/lib/awstats, which we will put on a persistent volume

Creating a Dockerfile for AWStats

Klutch.sh automatically detects a Dockerfile in the repository root and uses it for deployment. You do not select Docker explicitly in the UI or specify the Dockerfile path; detection is automated.

The Dockerfile below installs Apache, AWStats, and configures a basic AWStats CGI interface served over HTTP on port 80 (the recommended internal port for this app on Klutch.sh).

Create a Dockerfile in the root of your project:

FROM debian:stable-slim


ENV DEBIAN_FRONTEND=noninteractive


# Install Apache, AWStats, and required tools
RUN apt-get update && \
    apt-get install -y --no-install-recommends \
      apache2 \
      awstats \
      libapache2-mod-perl2 \
      cron \
      ca-certificates && \
    rm -rf /var/lib/apt/lists/*


# Enable CGI and required Apache modules
RUN a2enmod cgi alias && \
    a2enmod perl


# Configure AWStats Apache alias (basic example)
RUN echo 'Alias /awstatsclasses "/usr/share/awstats/lib/"' >> /etc/apache2/conf-available/awstats.conf && \
    echo 'Alias /awstats-icon "/usr/share/awstats/icon/"' >> /etc/apache2/conf-available/awstats.conf && \
    echo 'ScriptAlias /awstats/ "/usr/lib/cgi-bin/"' >> /etc/apache2/conf-available/awstats.conf && \
    a2enconf awstats


# Copy AWStats configuration
COPY awstats.conf /etc/awstats/awstats.klutch.conf


# Ensure data and log directories exist and are writable
RUN mkdir -p /var/lib/awstats /var/log/apache2 && \
    chown -R www-data:www-data /var/lib/awstats /var/log/apache2


# Simple cron job to update stats every 10 minutes
RUN echo '*/10 * * * * root /usr/lib/cgi-bin/awstats.pl -config=klutch -update > /dev/null 2>&1' \
    > /etc/cron.d/awstats-update && \
    chmod 0644 /etc/cron.d/awstats-update && \
    crontab /etc/cron.d/awstats-update


# Environment variable for Apache listen port
ENV PORT=80


EXPOSE 80


# Start cron and Apache in the foreground
CMD service cron start && apachectl -D FOREGROUND

Key Points About This Dockerfile

  • AWStats is exposed via Apache on port 80, which will be your internal port in Klutch.sh.
  • awstats.conf is copied as awstats.klutch.conf, and the cron job updates stats regularly based on that config.
  • The data directory /var/lib/awstats and log directory /var/log/apache2 are created and owned by www-data, which you will mount as persistent volumes.

Optional: Local Testing with Docker

You can test your image locally before deploying:

Terminal window
# Build the image
docker build -t awstats-klutch .


# Run the container, mapping host port 8080 to container port 80
docker run -d \
  --name awstats-test \
  -p 8080:80 \
  -v "$(pwd)/sample-logs:/var/log/apache2" \
  -v "$(pwd)/awstats-data:/var/lib/awstats" \
  awstats-klutch

Then open http://localhost:8080/awstats/awstats.pl?config=klutch to view the AWStats interface.

For a production-ready setup, ensure your webserver logs (from your main app) are shipped or mounted into /var/log/apache2 inside the AWStats container.

Pushing Your AWStats Project to GitHub

Once your Dockerfile and configuration are ready, push them to a GitHub repository:

Terminal window
git add .
git commit -m "Initial AWStats Docker setup for Klutch.sh"
git branch -M main
git remote add origin https://github.com/your-username/awstats-klutch.git
git push -u origin main

Klutch.sh will use this GitHub repository as the source for your deployment.

Creating an AWStats App on Klutch.sh

With your repository in place, you can now create and configure the app in the Klutch.sh dashboard.

1. Log In to the Dashboard

Go to klutch.sh/app and sign in.

2. Create a Project

Navigate to Create Project and give your project a descriptive name (for example, awstats-analytics).

3. Create a New App

Open Create App and configure:

  • Git Source: GitHub
  • Repository: Select the AWStats repository you created
  • Branch: Choose the branch you want to deploy (for example, main)

Klutch.sh will automatically detect the Dockerfile in the repository root and use it for the build.

4. Configure Traffic Type and Internal Port

  • Traffic Type: Select HTTP (AWStats is served over HTTP via Apache).
  • Internal Port: Set to 80, which is the port exposed in your Dockerfile and used by Apache inside the container.

5. Environment Variables

Add any runtime environment variables needed by your setup. Common examples:

  • TZ – your timezone (for example, UTC or America/New_York) so that AWStats reports align with your time zone.
  • Any custom variables you might use in extended configuration or log-processing scripts.

If you choose to deploy an AWStats-based application without a Dockerfile and rely on Nixpacks detection instead, you can customize commands using:

  • BUILD_COMMAND – to override the default build command for Nixpacks.
  • START_COMMAND – to override the default start command for Nixpacks.

Set these as environment variables in the Klutch.sh dashboard to control how Nixpacks builds and runs your app.

6. Attach Persistent Volumes

AWStats requires persistent storage to:

  • Retain analytics data across deployments
  • Store and access server log files for historical analysis

Attach volumes in the app’s storage/volumes section:

  • AWStats Data Volume

    • Mount path: /var/lib/awstats
    • Size: Choose based on how much historical analytics data you expect to keep (for example, 5 GiB, 10 GiB, or more).

  • Log Volume

    • Mount path: /var/log/apache2
    • Size: Size depends on log retention; start with something like 5 GiB and increase as needed.

Make sure your log pipeline (either an upstream proxy, main app, or separate log shipper) writes logs into the mount path used inside the AWStats container.

7. Compute and Scaling

Select compute resources appropriate for your workload:

  • CPU: 1–2 cores are usually enough for small to medium traffic, more for high-traffic sites.
  • Memory: 512MB–1GB minimum; increase if you analyze large log files or many sites.
  • Instances: Start with a single instance. If you run multiple instances, ensure they share the same persistent volumes so that analytics data remains consistent.

8. Deploy the App

Click Create to trigger the deployment. Klutch.sh will:

  • Clone your GitHub repository
  • Automatically detect and build from the Dockerfile
  • Provision the compute resources and attach volumes
  • Route HTTP traffic to your container on internal port 80

Once the deployment succeeds, your app will be available at a URL like:

https://example-app.klutch.sh

You can typically access AWStats at:

https://example-app.klutch.sh/awstats/awstats.pl?config=klutch

Verifying AWStats on Klutch.sh

After deployment:

  1. Visit your app URL (https://example-app.klutch.sh) and append the AWStats path if needed.
  2. Confirm that:
    • The AWStats CGI interface loads without errors.
    • Log data appears in the reports (visits, unique visitors, pages, hits, bandwidth).
    • Time and hostname/domain settings match your expectations.

If you do not see any data:

  • Verify that access logs are being written into /var/log/apache2 in the container.

  • Confirm that the cron job (or manual update command) is updating statistics:

    Terminal window
    # Inside the container (for debugging only)
    /usr/lib/cgi-bin/awstats.pl -config=klutch -update

Integrating AWStats with Your Applications

AWStats typically analyzes logs generated by other applications or web servers. When running on Klutch.sh, you can:

  • Configure your main application or reverse proxy to stream or copy access logs into the mounted log volume path (/var/log/apache2).
  • Run AWStats as a dedicated analytics app alongside your primary HTTP app(s), each deployed as separate Klutch.sh apps.

Example: Custom Log Format Note

If your app uses a custom log format, update the LogFormat directive in awstats.conf to match your log pattern. AWStats supports several built-in formats and can be customized to parse specific patterns as needed.

Troubleshooting

AWStats Page Not Loading

  • Ensure the app’s traffic type is set to HTTP, not TCP.
  • Confirm the internal port is set to 80 and matches the EXPOSE 80 in your Dockerfile.
  • Check deployment logs in the Klutch.sh dashboard for Apache or AWStats errors.

No Data or Empty Reports

  • Verify that logs are being written into /var/log/apache2 in the container.
  • Check that your LogFile path in awstats.conf matches the actual log file path.
  • Run the AWStats update command manually inside the container to identify parsing errors.
  • Ensure the persistent volume for /var/log/apache2 is correctly mounted and has enough space.

Data Not Persisting Across Deployments

  • Confirm that /var/lib/awstats is backed by a persistent volume.
  • Verify that the mount path in the Klutch.sh dashboard exactly matches the Dockerfile’s data directory.
  • Make sure you haven’t changed the data directory path between image versions without updating the volume configuration.

Deploying an AWStats app on Klutch.sh with a Dockerfile gives you a powerful, self-hosted analytics platform that keeps your traffic data under your control. With a carefully crafted Dockerfile, correctly configured internal port, and persistent volumes for logs and analytics data, you can run reliable, long-lived AWStats dashboards alongside your production applications on Klutch.sh.