The Admin Suite is a comprehensive, yet remarkably simple and user-friendly solution meticulously crafted for the efficient monitoring and management of Linux servers. It is primarily designed to cater to the needs of single-server instances, making it an ideal choice for small to medium-sized deployments or dedicated server environments. While optimized for Debian-based systems, its core functionalities are broadly applicable across various Linux distributions.
This suite empowers administrators with a centralized dashboard to oversee critical server operations, track performance metrics, manage services, and ensure the overall health and stability of their infrastructure. Its intuitive interface simplifies complex administrative tasks, making server management accessible even to those with limited command-line experience, while still providing powerful tools for seasoned professionals.
Admin Suite is an open-source project, and its entire codebase is available on GitHub. We welcome contributions from the community to help improve and expand its functionalities.
The Admin Suite is engineered with a robust and efficient tech stack, prioritizing performance, stability, and ease of deployment. A key architectural decision was to design the application for bare-metal deployment rather than as a containerized solution. This approach minimizes overhead, provides direct access to server resources, and simplifies the operational footprint, making it exceptionally straightforward to install and manage without the complexities often associated with container orchestration.
At its core, the application leverages PHP 8+ for its powerful backend logic and API functionalities. For data persistence, the metrics component and other critical data are stored in a MySQL database, chosen for its reliability, widespread adoption, and robust feature set. Furthermore, the application utilizes the filesystem for caching mechanisms instead of external solutions like Redis, further reducing external dependencies and simplifying the overall system architecture. This streamlined approach ensures that Admin Suite remains lightweight, highly performant, and easy to maintain.
To ensure optimal performance and compatibility, the Admin Suite requires the following software and PHP extensions to be installed on your server environment:
The following PHP extensions are crucial for various functionalities within the Admin Suite:
Installing the Admin Suite is designed to be a straightforward process, mirroring the simplicity of deploying any standard PHP project. Follow these detailed steps to get your Admin Suite up and running:
admin-suite-<tag>.tar.gz
release archive from the GitHub Releases
page, upload it to your server, and extract it to the directory. If you prefer working
directly with the source, you can clone it via HTTPS instead:
git clone https://github.com/lukasbecvar/admin-suite.gitpublic/ directory. This configures your web server to serve the Admin
Suite application.
.env.prod file to .env
in the root directory of the project. This file will contain your specific environment
configurations, such as database credentials and application settings. Customize it according to
your server environment.
npm install && composer installnpm run build.env configuration:
php bin/console doctrine:database:create --if-not-exists--no-interaction flag ensures the process runs non-interactively:
php bin/console doctrine:migrations:migrate --no-interactionsystemd-config documentation within the repository for detailed instructions on
configuring this service.
The Admin Suite offers flexible configuration options, allowing you to tailor its behavior to your specific environment and operational requirements. Configuration is primarily managed through environment variables and dedicated suite configuration files.
Environment variables are crucial for defining sensitive settings and environment-specific parameters
without hardcoding them into the application. These variables are loaded from the .env
file located in the root directory of your project. You should create this file and populate it with
your unique configurations, such as database connection strings, API keys, and other critical
settings. This approach ensures that sensitive information is kept separate from the codebase and
can be easily managed across different deployment environments (e.g., development, staging,
production).
The environment variables are loaded from the .env file. Create this file in the project root and populate it with your configuration.
| Variable | Description | Example value |
|---|---|---|
| APP_ENV | Application environment | prod |
| APP_SECRET | Secret encryption key | 0cb9325e8b4b59a90249865085 |
| TRUSTED_HOSTS | Trusted URL hosts | becvar.xyz,becvar.test |
| SSL_ONLY | Allow only SSL traffic | true |
| MAINTENANCE_MODE | Enable maintenance mode | true |
| PWA_APP_SUPPORT | Enable PWA app support | true |
| ADMIN_CONTACT | System maintainer contact email | admin@becvar.xyz |
| IP_APIS | List of APIs used to obtain the host server's public IP | https://ifconfig.me,https://example.tld |
| IP_INFO_API | API for getting information about visitor IP addresses | http://ip-api.com |
| AUTHOR_WEBSITE_URL | Author's website URL | https://becvar.xyz |
| PROJECT_GITHUB_URL | Project GitHub URL | https://github.com/lukasbecvar/admin-suite |
| RATE_LIMIT_ENABLED | Enable rate limit | false |
| RATE_LIMIT_INTERVAL | Rate limit interval | 60 |
| RATE_LIMIT_LIMIT | Rate limit limit | 100 |
| ANTI_LOG_TOKEN | Token to disable logging | 1234567890 |
| SYSTEM_LOGS_DIR | System logs directory | /var/log |
| DATABASE_LOGGING | Enable database logging | true |
| LOG_LEVEL | Log level | 4 |
| MEMORY_COST | Hash memory cost | 1024 |
| TIME_COST | Hash time cost | 10 |
| THREADS | Hash threads | 2 |
| LIMIT_CONTENT_PER_PAGE | Limit items per page | 10 |
| MONITORING_INTERVAL | Monitoring interval | 60 |
| METRICS_SAVE_INTERVAL | Metrics save interval | 60 |
| NETWORK_SPEED_MAX | Network speed (Mbps) limit for usage calculation | 1000 |
| DATABASE_DRIVER | Database driver | pdo_mysql |
| DATABASE_HOST | Database host | localhost |
| DATABASE_PORT | Database port | 3306 |
| DATABASE_NAME | Database name | admin_suite |
| DATABASE_USERNAME | Database user | root |
| DATABASE_PASSWORD | Database password | root |
| MAILER_ENABLED | Enable mailer | true |
| MAILER_HOST | Mailer host | localhost |
| MAILER_PORT | Mailer port | 25 |
| MAILER_USERNAME | Mailer username | service@becvar.xyz |
| MAILER_PASSWORD | Mailer password | password |
| PUSH_NOTIFICATIONS_ENABLED | Enable push notifications | true |
| PUSH_NOTIFICATIONS_MAX_TTL | Maximum TTL for push notifications | 86400 |
| PUSH_NOTIFICATIONS_CONTENT_ENCODING | Push notifications content encoding | aes-256-gcm |
| PUSH_NOTIFICATIONS_VAPID_PUBLIC_KEY | Public key for push notifications | 12938747T6T6R236 |
| PUSH_NOTIFICATIONS_VAPID_PRIVATE_KEY | Private key for push notifications | 12938747T6T6R236 |
In addition to the environment variables, Admin Suite relies on JSON configuration files that
live in the config/suite directory. Each file governs a focused portion of the
system and can be overridden by copying it into the project root (for example
protected-columns.json) and editing the copy there. The application automatically
prefers the custom file while leaving the default variant untouched, which makes upgrades safe
and keeps your changes easily trackable.
Available suite configuration files:
protected-columns.json — Array of database column names that the Table Browser must hide
completely. Add fields that carry credentials (e.g., authentication_string,
auth_token) to keep them obscured from exports and screenshots.
blocked-usernames.json — Array of reserved usernames. During registration the backend
matches the chosen username against this list to prevent the creation of accounts such as
root, administrator, etc. Extend it with any internal-only aliases.
feature-flags.json — Key/value map of booleans that toggle whole components. Each property
name matches a module (e.g., monitoring, terminal, database-manager);
set it to true to expose the component in the UI or false to hide it.
package-requirements.json — Defines what the diagnostic command checks for. It contains two arrays:
php-extensions: Extension names such as pdo_mysql, gd
or intl.system-packages: Binaries that should be present on the host (e.g.,
composer, ufw, git, zip). The Requirements
check command iterates over both arrays and reports missing dependencies.services-monitoring.json — Master definition of every monitored service. It is a map where each key is an internal identifier and the value describes the service:
service_name: Unique slug used in logs and API calls.display_name: Human friendly label rendered on the dashboard.type: Either systemd (checked via systemctl) or
http (polled via HTTP requests).monitoring/display: Toggle whether the service is actively checked
and/or shown in the UI without deleting the definition.config_files: List of files to expose in the detail drawer so operators can open
related configuration from the UI.url (HTTP only): Endpoint to call; accept_codes holds the HTTP
status codes that count as healthy; max_response_time expresses the SLA in
milliseconds.metrics_monitoring: Nested object with collect_metrics boolean and
metrics_collector_url string. When enabled, Admin Suite fetches custom metrics
from the provided URL.exception_file: Absolute path to the log file that should be tailed inside the
monitoring UI (optional for purely systemd services).terminal-aliases.json — Object where each key is the alias exposed in the in-browser
terminal and the value is the exact command executed (e.g., ll →
ls -alF -v). Updating this file lets you roll out helper shortcuts to all operators.
terminal-blocked-commands.json — Array of commands that the terminal will refuse to run.
Add resource-heavy or destructive binaries (bpytop, vim, etc.) to keep
the shared environment safe.
Any change to these files is picked up immediately; you only need to clear the cache if you modify them while running in production with long-lived OPcache.
The Admin Suite employs a meticulously designed, completely custom user authentication system, built from the ground up to ensure robust security and seamless user management. This bespoke system handles user registration, login, and permission management, providing a tailored experience that integrates perfectly with the application's functionalities.
A unique aspect of the initial setup is that only the very first user attempting to register through the application's web interface will be granted administrative privileges. This mechanism ensures a secure initial deployment, preventing unauthorized access during the critical setup phase. Subsequent user registrations can then be managed and assigned roles by the primary administrator.
For user sessions, the Admin Suite utilizes standard PHP sessions, ensuring secure and stateful interactions. Additionally, a 'remember me' feature is implemented using secure cookies, allowing users to maintain their login status across browser sessions for enhanced convenience, while adhering to best practices for secure cookie handling.
Machine-to-machine integrations can reuse any user’s authentication token as an API key. Sending the
token in the API-KEY HTTP header automatically hydrates the session, so the request
inherits the same permissions as if the user had logged in via the UI. API access must be explicitly
allowed per user (the allow_api_access flag), and tokens can be rotated from the Users Manager
module. Every API-key authentication attempt is logged under the
api-authentication channel for auditing.
The Admin Suite application is designed with a strong focus on security to protect sensitive data and ensure system integrity. Key security features include:
The Admin Suite provides a comprehensive and flexible monitoring system designed to keep you informed about the health and performance of your server and its services. It encompasses various monitoring facets, from service uptime to detailed system metrics and visitor tracking for web applications.
The core of the service monitoring functionality relies on a dedicated console command
(console app:monitoring:process) that runs continuously in an infinite loop. This
command actively checks the status of both HTTP-based services and systemd services. For robust
operation, this command should be configured to run as a persistent systemd service on your server.
Monitored services are meticulously defined within the
config/suite/services-monitoring.json configuration file, allowing for granular control
over what is monitored. To ensure timely alerts, it is essential to configure the monitoring
interval and specify an SMTP server or push notification settings via environment variables. The
real-time status and historical monitoring data for all configured services are then intuitively
displayed on the web dashboard page, providing a clear overview of your infrastructure's health.
The metrics component is an integral part of the monitoring process, designed to collect and store
vital performance data. Its operation is directly tied to the running monitoring process, ensuring
continuous data capture. This component diligently records average usage values for critical system
resources such as CPU, RAM, and storage, based on the interval defined in your .env
file (METRICS_SAVE_INTERVAL). This historical data is invaluable for analyzing
long-term performance trends, identifying bottlenecks, and planning resource allocation.
For web applications, the Admin Suite offers a specialized Metrics Collector, enabling you to gather
custom metrics directly from your monitored HTTP services. This feature allows for a deeper insight
into application-specific performance indicators. You can easily enable the Metrics Collector within
the services-monitoring.json file by setting collect_metrics to
true and specifying the metrics_collector_url. The Metrics Collector is
designed to accept simple key-value pairs (key as a string, value as an
integer or float), making it highly adaptable for various custom metrics.
{
"cpu_usage": 64,
"ram_usage": 77,
"storage_usage": 10
}This example demonstrates how your application can expose its internal metrics for collection by the Admin Suite.
The visitor tracking feature provides valuable insights into the usage of your HTTP-based services.
It allows you to monitor visitor activity, helping you understand user engagement and traffic
patterns. To activate this feature, you need to configure the specific service within the
services-monitoring.json file. It's crucial to specify both the service name and its
URL (the URL is used for verification against the HTTP_ORIGIN header).
Tracking is performed via a simple API call that needs to be integrated into your web application's frontend. Below is an example of how to implement this API call using JavaScript:
const visitorReferer = document.referrer || 'Unknown'
fetch('https://admin-suite.url/api/monitoring/visitor/tracking', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({
service_name: 'monitored-service-name',
referer: visitorReferer
})
})This snippet demonstrates how your web application can send visitor data to the Admin Suite for comprehensive tracking and analysis.
The Admin Suite ensures that administrators are always informed about critical events and system statuses through a robust notification system. This system is designed to deliver timely alerts, allowing for proactive management and rapid response to potential issues.
Notifications are primarily delivered through two channels:
The flexibility of these notification methods ensures that administrators can choose their preferred way to stay updated, guaranteeing that no critical event goes unnoticed.
The Admin Suite incorporates a comprehensive logging system designed to provide deep insights into both internal application activities and external events. This dual-purpose logging capability is crucial for auditing, debugging, and maintaining a secure and transparent operational environment.
The system facilitates two primary types of log storage, both managed efficiently within the database:
External services can push events to POST /api/external/log. The endpoint
accepts simple query parameters (name, message, level)
or an application/xml payload with the same fields. Each call must include a valid API-KEY header that belongs
to a user with API access enabled.
curl -X POST https://admin-suite/api/external/log \
-H "API-KEY: <user-token>" \
--data-urlencode "name=backup-service" \
--data-urlencode "message=Backup finished in 142s" \
--data-urlencode "level=4"Successful requests return a JSON confirmation, while missing fields, malformed XML, or invalid credentials generate descriptive error responses so callers can react immediately.
By storing logs directly in the database, the Admin Suite ensures data integrity, facilitates complex querying, and provides a persistent record of all events, making it an indispensable tool for system administrators.
These frames are captured directly from a live Admin Suite environment, so every widget, badge, and chart shown below reflects the production-ready state of the platform rather than mockups or drafts. Treat this section as a quick visual audit of how the tooling behaves once it is deployed in a real environment.
The dashboard page concentrates key health indicators.
The Monitoring hub shows an internal daemon list, HTTP checks, and drill-downs for each service.
The Metrics Dashboard page provides raw and historical data.
The Database Manager bundles multi-level lists, quick actions, and server statistics without opening a separate client.
Log Manager exposes a severity-colored table for app/API events plus dedicated system-log and exception-file explorers.
The Filesystem Browser mixes breadcrumb navigation, creation menus, and inline action bars for managing files remotely.
The embedded terminal is a browser-to-server shell wired into the /api/system/terminal endpoints.
user@host:cwd$ and updates as you move around, so you always know where commands will execute.
The Diagnostics page runs both host and suite checks and summarizes them in color-coded cards.
The System Audit dashboard aggregates server info, security lists, and audit trails.
Todo Manager is the operational runbook for open and closed tasks.
User Manager keeps every operator and their actions auditable.
The Settings hub groups account preferences, suite JSON files, and feature flags inside one landing page.