Skip to content

lukasbecvar/admin-suite

BranchesTags

Repository files navigation

Admin suite

Solution for administration and monitoring linux servers

Documentation | License | Author website

Dashboard preview

Dashboard

Description

Simple & user-friendly solution for monitoring and managing Linux servers, primarily designed for single server instances debian-based systems.

Tech stack

Development

The complete stack for development is in Docker Compose, including PHP, Node, and Composer. You just need to run the sh docker-start-dev.sh script to launch it.

Production

The application is designed to run on bare-metal rather than as a containerized application. For this reason, it requires minimal software to operate, making it easy to install and manage. For example, the metrics component stores data in MySQL, and the cache uses the filesystem instead of Redis.

Index

Installation

Installation is very simple like any other PHP project.

  • Download the latest prebuilt archive (admin-suite-<tag>.tar.gz) from the release assets: GitHub Releases page and extract it on your server or clone this repository
  • Create apache virtual host or nginx configuration like (apache-config)
  • Create .env file with your configuration (.env.prod)
  • Install dependencies npm install && composer install
  • Build frontend assets npm run build
  • Create database php bin/console doctrine:database:create --if-not-exists
  • Migrate database php bin/console doctrine:migrations:migrate --no-interaction
  • Create systemd service for monitoring process (console command infinite loop) (systemd-config)
  • Create main admin user using console command or web interface (webinterface allows to create user if users table is empty)
  • Create your custom suite configuration files in root directory (see Configuration)

Configuration

Environment variables

The environment variables are loaded from .env file. You can create .env file in root directory 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 Enable only ssl traffic true
MAINTENANCE_MODE Enable maintenance mode true
PWA_APP_SUPPORT Enable pwa app support true
ADMIN_CONTACT The system maintener contact email admin@becvar.xyz
IP_APIS The list of APIs to get host server pulic ip IP_APIS=IP_APIS=https://ifconfig.me,url2,url2
AUTHOR_WEBSITE_URL The system maintener contact email https://becvar.xyz
PROJECT_GITHUB_URL The system maintener contact email https://github.com/lukasbecvar/admin-suite
IP_INFO_API API for get information about visitor ip http://ip-api.com
RATE_LIMIT_ENABLED Enable rate limit false
RATE_LIMIT_INTERVAL Rate limit interval 60
RATE_LIMIT_LIMIT Rate limit limit 100
TERMINAL_JOB_MAX_RUNTIME Maximum runtime for terminal job 7200
ANTI_LOG_TOKEN Token for 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 Push notifications max ttl 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

Suite configuration

The default admin suite configuration is stored in json files in config/suite directory. You can create your own configuration files in app root and override default configuration.

  • config/suite/protected-columns.json - list of protected columns (hidden in table browser)
  • config/suite/blocked-usernames.json - list of blocked usernames
  • config/suite/package-requirements.json - list of packages and php extensions to be installed
  • config/suite/services-monitoring.json - list of services to be monitored
  • config/suite/terminal-aliases.json - list of terminal aliases
  • config/suite/terminal-blocked-commands.json - list of blocked terminal commands

Requirements

Software

  • PHP 8.5 and compatible web server
  • MySQL 8 or higher
  • Composer
  • NPM

PHP extensions

  • PHP-PDO extension (db driver)
  • PHP-OpenSSL extension
  • PHP-Intl extension
  • PHP-Curl extension
  • PHP-DOM extension
  • PHP-GMP extension
  • PHP-GD extension

Authentication

Authentication uses a completely custom user system with a username and password, managed by the application user manager. Only the first user can use the registration form to create an admin user. Login uses standard PHP session and cookie for the 'remember me' feature.

API key authentication

Backend-to-backend consumers can call any /api/** route by reusing an existing user token as an API key and sending it via the API-KEY HTTP header. After the middleware validates the token, it hydrates the Symfony session, so the request runs with the same authorizations as if the user had passed through the HTML login form.

Issuing and rotating tokens

  • Every user record has a randomly generated value in the token column. You can rotate it from Users Manager → Regenerate authentication token (route /manager/users/token/regenerate) or through your own automation by calling AuthManager::regenerateSpecificUserToken.
  • API access is additionally guarded by the allow_api_access flag that you must enable to use the user-token as an API key.

Using the header

  • Attach the header to any API call: curl -H "API-KEY: <user-token>" https://admin-suite/api/system/resources.
  • Only /api/** paths accept header-based login. Browser sessions still rely on the standard cookie-based flow.
  • Each API request is fully audited. Invalid or disabled tokens are logged under the api-authentication channel so you can track brute-force attempts.

Monitoring

Services monitoring

HTTP and systemd services monitoring is ensured by a console command (infinite loop) console app:monitoring:process. This command needs to be run as a service, and the monitored services should be defined in the services config file in config/suite/services-monitoring.json. it is necessary to set the monitoring interval and the SMTP server or push notifications in the environment variables for sending alerts. The status and monitoring data can then be viewed in the web dashboard page.

Metrics

The metrics component stores data during the monitoring process, so its function requires the monitoring process to be running. The metrics store average usage values for CPU, RAM, and storage during the interval set in .env as METRICS_SAVE_INTERVAL.

Metrics Collector for HTTP services

The Metric Collector allows you to collect metrics from monitored HTTP web applications. You can enable the metric collector in the services-monitoring.json file (services-monitoring.json) by setting collect_metrics to true and specifying the metrics_collector_url. The Metric Collector accepts key (string) and value (int|float).

Example response from the metric collector:

{
  "cpu_usage": 64,
  "ram_usage": 77,
  "storage_usage": 10,
}

Visitor tracking

The visitor tracking feature allows you to monitor visitors to HTTP-based services. To enable tracking, you need to configure the service in the (services-monitoring.json) file. The service name and URL must be specified (the URL is used for verification as HTTP_ORIGIN). Tracking is performed via an API that needs to be called from your application.

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
    })
})

Notifications

Notifications from application are sent to admin users via web push notifications if the admin enables them. It also allows sending alerts directly to the admin's email.

Logging

The system stores user actions in the database (respecting LOG_LEVEL, anti-log cookies, and DATABASE_LOGGING). You can also push structured events from other services through a dedicated API.

External log ingestion API

  • Endpoint: POST /api/external/log
  • Authentication: API-KEY header with a token that belongs to a user allowed to call the API
  • Payloads: either query parameters (name, message, level) or an application/xml body with the same fields
  • Levels: use the numeric constants from LogManager (1=CRITICAL, 2=WARNING, 3=NOTICE, 4=INFO). Only levels lower than or equal to the configured LOG_LEVEL are saved.

Example with query parameters:

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"

Example with XML payload:

curl -X POST https://admin-suite/api/external/log \
  -H "API-KEY: <user-token>" \
  -H "Content-Type: application/xml" \
  -d '<log><name>payment-worker</name><message>Bank API timeout</message><level>2</level></log>'

Successful requests return {"status":"success"}; missing fields, invalid XML, or bad credentials respond with {"status":"error","message":"..."} and the relevant HTTP code so you can react from the caller.

Contributing

Contributions are welcome! Please fork this repository and submit pull requests for any features, bug fixes, or enhancements. If you have any questions or need help, feel free to open an issue or contact me directly.

Dependencies

License

This software is licensed under the MIT license.

About

Solution for Linux server administration and monitoring.

lukasbecvar.github.io/admin-suite/

Topics

linux php admin database symfony monitoring tool

Resources

Readme

License

MIT license
Activity

Stars

20 stars

Watchers

2 watching

Forks

0 forks
Report repository

Releases 100

10.0 Latest
Dec 1, 2025
+ 99 releases

Languages