Skip to main content
This page turns a working local installation into a development environment: verbose errors, no caching, rebuilt frontend assets on save, and a cron runner.
This page applies to Aikeedo 5.x. Class names, paths and signatures match the 5.0 source code.

​
Prerequisites

  • A local Aikeedo installation. If you don’t have one, follow the local installation guide first.
  • PHP 8.2 or newer with the intl, gd and bcmath extensions
  • MySQL 8.0 or newer
  • Composer 2
  • Node.js 20.19+ or 22.12+ with npm, needed only for frontend work
The release archive ships with vendor/ already installed, so you don’t need composer install to run Aikeedo. It does not ship node_modules/, so you need npm install before you can run the Vite dev server.

​
Step 1: Configure the environment

Edit .env in the installation root:
.env
Never leave DEBUG=true on a production site. Debug mode exposes stack traces and disables caching.

​
Step 2: Start the frontend dev server

Aikeedo builds the app, admin and auth bundles with Vite.
Vite serves on port 5173. Keep the process running: it rebuilds on save and reports build errors.
You only need Vite when you change files under resources/assets. For PHP or Twig work, leave HMR=0 and use the prebuilt assets in public/assets.

​
How assets resolve

Templates resolve asset URLs through the asset Twig filter. With HMR enabled, that filter points at ASSETS_SERVER instead of the manifest.

​
Step 3: Serve the application

Use PHP’s built-in server for local work:
Open http://localhost:8000. Run this in a second terminal so Vite keeps running in the first.
The built-in server is single-threaded. Streamed responses, such as chat, occupy the process while they run, so a second request can appear to hang. Use php -S with a worker-capable setup, Docker, Valet or nginx with PHP-FPM if that gets in your way.

​
Step 4: Run cron

Scheduled work, including subscription renewals, usage resets, statistics and import jobs, runs through cron.php. Nothing schedules it for you locally, so run it by hand when you need it:
To mirror production, add a crontab entry that runs it every minute. See Initial setup for the production configuration.

​
Step 5: Use the console

bin/console exposes the Symfony Console application, including Doctrine’s commands:
Commands you’ll use often in development: See Console commands for the full list.

​
Development workflow

  • PHP changes apply on the next request. If you add or move a route, clear the route cache or keep CACHE=false.
  • Twig changes apply immediately while caching is off.
  • Asset changes are rebuilt by Vite and pushed to the browser.
  • Plugin and theme changes may need a cache clear, and a new plugin needs composer require. See the plugin quickstart and theme quickstart.
Clear caches at any time from Status → Clear cache in the admin panel, which also rebuilds the browser translation catalogs.

​
Build for production

This writes optimized bundles to public/assets, copies resources/static into the web root, and refreshes public/.vite/manifest.json. Set HMR=0, DEBUG=false and CACHE=true before you deploy.

​
Troubleshooting

Vite isn’t running, or ASSETS_SERVER doesn’t match its port. Start npm run dev, or set HMR=0 to use the built assets.
Caching is on. Set CACHE=false, or clear the cache from Status → Clear cache.
Debug mode enables strict variables. Guard optional values with {% if foo is defined %}.
Routes are cached when CACHE=true and DEBUG=false. Turn caching off during development, or clear the cache.
Logs are in var/log/app-YYYY-MM-DD.log and var/log/error-YYYY-MM-DD.log. Check that var/ is writable by your PHP user.