Deploying GoAccess

Introduction

GoAccess is an open-source, real-time web log analyzer and interactive viewer that provides fast, valuable insights from your web server access logs. Designed to be run in a terminal or through your browser, GoAccess parses logs and generates beautiful HTML reports with real-time updates.

Built with performance in mind, GoAccess can process millions of log entries in seconds, making it ideal for high-traffic websites that need immediate visibility into their traffic patterns, visitor behavior, and potential issues.

Key highlights of GoAccess:

• Real-Time Analysis: Metrics update every 200ms in terminal mode, every second in HTML output
• Multiple Log Formats: Supports Apache, Nginx, Amazon S3, CloudFront, Elastic Load Balancing, and custom formats
• Beautiful HTML Reports: Generate self-contained, interactive HTML dashboards
• Terminal Interface: ncurses-based interface for quick analysis
• WebSocket Support: Real-time HTML reports with live updates via WebSocket
• Geolocation: Track visitor locations with GeoIP support
• JSON/CSV Export: Export data for further analysis or integration
• Lightweight: Minimal dependencies and low resource usage
• 100% Open Source: Licensed under MIT

This guide walks through deploying GoAccess on Klutch.sh using Docker, configuring log analysis, and setting up real-time HTML dashboards.

Why Deploy GoAccess on Klutch.sh

Deploying GoAccess on Klutch.sh provides several advantages for web log analysis:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds GoAccess without complex orchestration. Push to GitHub and your analytics dashboard deploys automatically.

Persistent Storage: Attach persistent volumes for log files and generated reports. Historical data survives container restarts.

HTTPS by Default: Klutch.sh provides automatic SSL certificates for secure access to your analytics dashboard.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates trigger automatic redeployments.

Scalable Resources: Allocate CPU and memory based on log volume and analysis complexity.

Custom Domains: Assign a custom domain for your GoAccess dashboard.

Always-On Availability: Your analytics dashboard remains accessible 24/7.

Prerequisites

Before deploying GoAccess on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your GoAccess configuration
• Web server access logs to analyze
• Basic familiarity with Docker and containerization concepts
• Understanding of your web server’s log format

Understanding GoAccess Architecture

GoAccess is designed for simplicity and performance:

Log Parser: The core engine parses various log formats including Apache Combined/Common, Nginx, CloudFront, and custom formats.

Data Storage: GoAccess can use in-memory storage or on-disk databases for persistence across sessions.

Output Modes: Supports terminal (ncurses), static HTML, and real-time HTML with WebSocket updates.

Modular Panels: Displays data in configurable panels including visitors, requests, static files, referrers, user agents, and more.

Preparing Your Repository

To deploy GoAccess on Klutch.sh, create a GitHub repository containing your Dockerfile and configuration.

Repository Structure

goaccess-deploy/
├── Dockerfile
├── goaccess.conf
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM allinurl/goaccess:latest

# Copy configuration file
COPY goaccess.conf /etc/goaccess/goaccess.conf

# Create directories for logs and reports
RUN mkdir -p /var/log/goaccess /var/www/html

# Expose HTTP port for the dashboard
EXPOSE 7890

# Default command to run GoAccess with real-time HTML output
CMD ["goaccess", "--config-file=/etc/goaccess/goaccess.conf", "--real-time-html", "--ws-url=wss://${GOACCESS_HOST}:443/ws"]

Advanced Dockerfile with Nginx

For serving HTML reports with authentication:

FROM debian:bullseye-slim

# Install GoAccess and Nginx
RUN apt-get update && apt-get install -y \
    goaccess \
    nginx \
    && rm -rf /var/lib/apt/lists/*

# Copy configuration files
COPY goaccess.conf /etc/goaccess/goaccess.conf
COPY nginx.conf /etc/nginx/conf.d/default.conf

# Create directories
RUN mkdir -p /var/log/goaccess /var/www/html

# Copy startup script
COPY start.sh /start.sh
RUN chmod +x /start.sh

# Expose ports
EXPOSE 80

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
  CMD curl -f http://localhost/ || exit 1

CMD ["/start.sh"]

Creating the goaccess.conf File

Create a goaccess.conf configuration file:

# GoAccess Configuration File

# Time format for Apache Combined Log Format
time-format %H:%M:%S

# Date format for Apache Combined Log Format
date-format %d/%b/%Y

# Log format - Apache Combined Log Format
log-format COMBINED

# Output to HTML
output /var/www/html/report.html

# Enable real-time HTML report
real-time-html true

# WebSocket server port
port 7890

# Enable all panels
with-output-resolver false

# Enable mouse support in terminal
mouse-support true

# Color scheme
color-scheme 2

# Ignore crawlers
ignore-crawlers true

# Set the GeoIP database path if using geolocation
#geoip-database /usr/share/GeoIP/GeoLite2-City.mmdb

Creating the .dockerignore File

Create a .dockerignore file:

.git
.github
*.md
README.md
LICENSE
.gitignore
*.log
.DS_Store

Environment Variables Reference

Variable	Required	Default	Description
GOACCESS_HOST	Yes	-	Hostname for WebSocket connections
LOG_FORMAT	No	COMBINED	Log format (COMBINED, COMMON, etc.)
TZ	No	UTC	Timezone for log parsing

Deploying GoAccess on Klutch.sh

Once your repository is prepared, follow these steps to deploy GoAccess:

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile goaccess.conf .dockerignore README.md
git commit -m "Initial GoAccess deployment configuration"
git remote add origin https://github.com/yourusername/goaccess-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “goaccess” or “web-analytics”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your GoAccess Dockerfile.

Configure HTTP Traffic

GoAccess serves its web interface over HTTP. In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 7890 (or 80 if using Nginx)

Set Environment Variables

In the environment variables section, add:

Variable	Value
GOACCESS_HOST	your-app-name.klutch.sh
TZ	Your preferred timezone

Attach Persistent Volumes

Persistent storage is important for GoAccess. Add the following volumes:

Mount Path	Recommended Size	Purpose
/var/log/goaccess	10 GB	Access logs for analysis
/var/www/html	1 GB	Generated HTML reports

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will:

• Detect your Dockerfile automatically
• Build the container image
• Attach the persistent volumes
• Start the GoAccess container
• Provision an HTTPS certificate

Access GoAccess

Once deployment completes, access your GoAccess dashboard at https://your-app-name.klutch.sh.

Feeding Log Data to GoAccess

Uploading Log Files

Transfer your web server logs to the GoAccess persistent volume. Options include:

Manual Upload: Use file transfer tools to upload logs to /var/log/goaccess

Remote Sync: Configure rsync or similar tools to periodically sync logs from your web server

Log Aggregation: Use log shipping tools like Filebeat or Fluentd to forward logs

Continuous Log Analysis

For real-time analysis, configure your log source to continuously append to a file that GoAccess monitors:

# In the container, run GoAccess with a log file
goaccess /var/log/goaccess/access.log -o /var/www/html/report.html --real-time-html

Multiple Log Sources

GoAccess can analyze multiple log files:

goaccess /var/log/goaccess/*.log -o /var/www/html/report.html --real-time-html

Configuring Log Formats

Predefined Formats

GoAccess supports several predefined formats:

• COMBINED: Apache Combined Log Format
• COMMON: Apache Common Log Format
• VCOMBINED: Virtual host combined log format
• VCOMMON: Virtual host common log format
• W3C: IIS W3C log format
• CLOUDFRONTSSL: Amazon CloudFront (SSL)
• CLOUDFRONT: Amazon CloudFront
• S3: Amazon S3

Custom Log Format

For custom log formats, define the pattern in goaccess.conf:

# Custom log format example
log-format %h %^[%d:%t %^] "%r" %s %b "%R" "%u"
date-format %d/%b/%Y
time-format %H:%M:%S

Understanding the Dashboard

Available Panels

GoAccess displays data across multiple panels:

Panel	Description
Unique Visitors	Daily unique visitors with hits and bandwidth
Requested Files	Most requested URLs/pages
Static Requests	Static file requests (images, CSS, JS)
Not Found	404 errors and missing resources
Hosts	Client IP addresses
Operating Systems	Visitor operating systems
Browsers	Visitor browsers
Referrers	External referring URLs
Referring Sites	Top referring domains
Keyphrases	Search engine keyphrases
Geo Location	Visitor countries (requires GeoIP)
Status Codes	HTTP response codes

Real-Time Updates

When using real-time HTML mode, the dashboard updates automatically via WebSocket. Metrics refresh every second, giving you instant visibility into current traffic patterns.

Security Considerations

Access Control

GoAccess dashboards may contain sensitive information. Consider:

• Authentication: Add HTTP Basic Auth via Nginx
• IP Restrictions: Limit dashboard access to specific IPs
• VPN Access: Require VPN connection for viewing
• Separate Instance: Run GoAccess on an internal network

Data Privacy

• Anonymization: Consider anonymizing IP addresses in logs before analysis
• Retention: Implement log rotation and retention policies
• Compliance: Ensure log handling complies with GDPR and other regulations

Troubleshooting Common Issues

No Data Displayed

Symptoms: Dashboard shows no visitors or data.

Solutions:

• Verify log files exist in the configured directory
• Check log format matches your actual logs
• Test with a sample log file to verify parsing
• Review GoAccess stderr for parsing errors

WebSocket Connection Failed

Symptoms: Real-time updates don’t work.

Solutions:

• Verify GOACCESS_HOST matches your deployment URL
• Ensure WebSocket port is accessible
• Check browser console for connection errors
• Confirm HTTPS is being used for WebSocket (wss://)

Incorrect Statistics

Symptoms: Numbers don’t match expected traffic.

Solutions:

• Verify log format configuration matches actual logs
• Check for bot/crawler filtering settings
• Ensure timezone is set correctly
• Verify all log files are being processed

High Memory Usage

Symptoms: Container runs out of memory.

Solutions:

• Use on-disk database mode for large log files
• Increase container memory allocation
• Process logs in smaller batches
• Enable log rotation to limit file sizes

Additional Resources

• Official GoAccess Website
• GoAccess Manual
• GoAccess GitHub Repository
• GoAccess FAQ
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying GoAccess on Klutch.sh gives you a powerful, real-time web log analyzer with beautiful HTML dashboards. The combination of GoAccess’s performance and Klutch.sh’s deployment simplicity means you can gain immediate insights into your web traffic without complex analytics infrastructure.

Whether you’re monitoring a personal blog or analyzing traffic for a high-volume website, GoAccess on Klutch.sh provides the visibility you need. With support for multiple log formats, real-time updates, and comprehensive visitor statistics, GoAccess transforms raw access logs into actionable intelligence.