dotkernel/admin

Dotkernel Admin Application


README

Dotkernel Admin is an application (skeleton) intended for quickly setting up an administration site for your platform. It's a fast and reliable way to manage records in your database with a simple table-based approach, and also to build reports and graphs to monitor your platform. The many graphical components at your disposal ensure an intuitive user experience.

Check out our demo.

Submit user admin and password dotadmin to authenticate yourself.

Documentation

Documentation is available at: https://docs.dotkernel.org/admin-documentation/

Badges

OSS Lifecycle PHP from Packagist (specify version)

GitHub issues GitHub forks GitHub stars GitHub license

Build Static codecov Qodana PHPStan

Getting Started

Clone the project

Using your terminal, navigate inside the directory you want to download the project files into. Make sure that the directory is empty before proceeding to the download process. Once there, run the following command:

git clone https://github.com/dotkernel/admin.git .

Install the project dependencies

composer install

You will be prompted with the below message to choose whether you want to inject ConfigProviders:

 Please select which config file you wish to inject 'Laminas\Validator\ConfigProvider' into:
  [0] Do not inject
  [1] config/config.php
  Make your selection (default is 1):

Type 0 to select [0] Do not inject and hit Enter.

We choose not to inject any ConfigProvider because Dotkernel Admin comes with all the required ConfigProviders already injected in config/config.php. Choosing to inject any extra ConfigProvider would cause having duplicates which are not allowed and would crash the application.

Development mode

Do not enable development mode in production!

If you're installing the project for development, you should enable development mode by running:

composer development-enable

You can disable development mode by running:

composer development-disable

You can check the development status by running:

composer development-status

Prepare config files

  • optional: to run/create tests, duplicate config/autoload/local.test.php.dist as config/autoload/local.test.php <- this creates a new in-memory database that your tests will run on

Setup database

Use an existing empty one or create a new MariaDB/MySQL database.

Recommended collation: utf8mb4_general_ci.

Running migrations

  • fill out the database connection params in config/autoload/local.php under $databases['default']
  • run the database migrations by using the following command:
php ./bin/doctrine-migrations migrate

This command will prompt you to confirm that you want to run it:

WARNING! You are about to execute a migration in database "<database>" that could result in schema changes and data loss. Are you sure you wish to continue? (yes/no) [yes]:

Hit Enter to confirm the operation.

Executing fixtures

Fixtures are used to seed the database with initial values and must be executed after migrating the database.

To list all the fixtures, run:

php ./bin/doctrine fixtures:list

This will output all the fixtures in the order of execution.

To execute all fixtures, run:

php ./bin/doctrine fixtures:execute

To execute a specific fixture, run:

php ./bin/doctrine fixtures:execute --class=FixtureClassName

More details on how fixtures work can be found in dotkernel/dot-data-fixtures documentation.

Mail configuration

If your application sends emails, you must configure an outgoing mail server under config/autoload/mail.global.php.

Sync GeoLite2 databases

Full sync

You can download/update all GeoLite2 databases at once by running the following command:

php ./bin/cli.php geoip:synchronize

The output should be similar to the below:

asn: n/a -> 2015-10-21 04:29:00
city: n/a -> 2015-10-21 04:29:00
country: n/a -> 2015-10-21 04:29:00

Selective sync

You can download/update a specific GeoLite2 database by running the following command:

php ./bin/cli.php geoip:synchronize -d <database>

Where <database> takes one of the following values: asn, city, country.

Get help for this command by running:

php ./bin/cli.php help geoip:synchronize

If you set up the synchronizer command as a cronjob, you can add the -q|--quiet option, and it will output data only if an error has occurred.

NPM Commands

To install dependencies into the node_modules directory run this command:

npm install

If the above command fails, it could be caused by user permissions of npm. Recommendation is to install npm through Node Version Manager.

The watch command looks for JavaScript/CSS file changes and recompiles the assets under the public assets:

npm run watch

Once finished working on the JavaScript/CSS files, run the below command to minify the public assets and prepare them for production:

npm run prod

Test the installation

If you are using virtual hosts as described in the [Dotkernel documentation] (https://docs.dotkernel.org/development/), you need to modify the permissions of the data, public/uploads and log folders:

chmod -R 777 data
chmod -R 777 public/uploads
chmod -R 777 log

Run the following command in your project's directory to start PHPs built-in server:

php -S 0.0.0.0:8080 -t public

Running command composer serve will do the same thing, but the server will time out after a couple of minutes.

If you are still getting exceptions or errors regarding some missing services, try running the following command:

php ./bin/clear-config-cache.php

Open a web browser and visit http://localhost:8080/.

You should see the Dotkernel Admin login page. If you ran the migrations you will have an admin user in the database with the following credentials:

  • Identity: admin
  • Password: dotadmin

Warning

Production only

Make sure you modify the default admin credentials.

Warning

Development only

session.cookie_secure does not work locally so make sure you modify your local.php, as per the following:

return [
  'session_config' => [
    'cookie_secure' => false,
  ],
];

Do not change this in local.php.dist as well because this value must remain true on production.