System Admin Guide

The TinyPixel instance admin site provides complete system administration capabilities for managing your self-hosted analytics platform. From here, you can manage all tracked sites, system users, memberships, and global settings.

# Accessing the Admin Site

# URL

Navigate to /admin on your TinyPixel instance.

# Authentication

The admin site uses HTTP Basic Authentication with:

  • Username: tiny_pixel
  • Password: Derived from your Rails secret key

You can retrieve the value of your derived password by running ./bin/rails tiny_pixel:system_admin_password on your TinyPixel instance.

Note: The admin site is only accessible to users who have access to your Rails secret key value. Do not share this value

# Dashboard

The admin dashboard (/admin) displays key statistics:

  • Total Sites: Count of all tracked websites
  • Total Users: Count of all registered users
  • System Settings: Quick access to global configuration

From here, you can navigate to manage sites, users, or system settings.

# Managing Sites

Access all your tracked sites from /admin/sites.

# Features

  • View Sites: See all tracked websites with their creation dates and property IDs.
  • Create a Site: Add a new site to track.
  • Edit a Site: Modify any site settings after creation, including retention policies and session configuration.
  • Delete a Site: Remove a site and all associated data. This action is permanent.

# Managing Users

Access all system users from /admin/users.

# Features

View Users: See all users with their email addresses and join dates.

Create a User: Add a new system user through one of two methods:

  1. Invite via Email (if email delivery is configured):
    • User receives an invitation email with a secure link
    • They can set their own password upon first login
  2. Set Temporary Password (for offline deployments):
    • A temporary password is generated immediately
    • Display it to the user (copy-to-clipboard provided)
    • User must reset the password on first login

View User Details: See all sites a user has access to and their assigned roles.

Manage Memberships: Assign users to sites with specific roles:

  • Member: Can view analytics
  • Admin: Can view analytics and manage site members

Resend Invitations: Re-send invitation emails to users who haven’t activated their accounts yet.

Delete a User: Remove a user from the system. Their access to all sites is revoked.

# System Settings

Configure global settings for your entire tiny_pixel deployment from /admin/system_settings.

# Allowed Registration Domains

Control which email domains are permitted for user registration. This is useful for:

  • Restricting registration to your organization’s email domain
  • Running a private instance for internal use only

To Configure:

  1. Navigate to /admin/system_settings
  2. Enter one domain per line (e.g., example.com)
  3. Save settings

Users registering with email addresses from these domains can sign up. If domains are configured, registration is restricted to only those domains.

# Common Tasks

# Adding a New User and Assigning Them to a Site

  1. Go to /admin/users
  2. Click “Create User”
  3. Enter their email and choose auth method (invite or password)
  4. After creation, click “Add Membership”
  5. Select a site and role (member or admin)
  6. Save

# Setting Up a Site with Custom Retention

  1. Go to /admin/sites
  2. Click “Create Site”
  3. Enter the site name
  4. Adjust settings:
    • Set Stats Retention to your desired duration (e.g., 90 days)
    • Set Session Timeout for your analytics use case
  5. Click “Create Site”

# Restricting Registration to Your Organization

  1. Go to /admin/system_settings
  2. In the “Allowed Registration Domains” section, enter your organization’s domains
  3. Save

Now only users with email addresses matching those domains can register.

# Security Considerations

  • Admin access is password-protected via HTTP Basic Auth
  • Credentials are derived from your Rails master key, not stored separately
  • All admin actions are logged through Rails’ audit trail
  • Destructive actions (delete site, delete user) require confirmation
  • The admin interface is not exposed through regular user authentication

Keep your Rails master key secure—anyone with access to it can access the admin site.

# Tips

  • Property IDs: Each site gets a unique Property ID. This is used in your tracking code and cannot be changed.
  • Salt Rotation: Salts are automatically rotated on your configured schedule. This helps maintain visitor privacy while preserving historical analytics.
  • Temporary Passwords: Temporary passwords expire after first use. Users must set a permanent password on their first login.
  • Backups: Before making large changes (like deleting sites or users), ensure you have a recent database backup.