System structure (Frontastic sandbox)

If you're into heavy debugging or are just curious how things work, looking into how the Frontastic sandbox is structured could help so we wanted to share that with you.

Within the Frontastic sandbox, you can see server logs (including Server Side Rendering (SSR) logs), look into the database, clear caches, and more.

To bring up the Frontastic sandbox, follow the steps in the Bringing up a Frontastic sandbox article. Then, you can reach into the Frontastic sandbox using ssh [email protected]<your-machine-host> (see the Frontastic studio for the password).

This brings you to a Linux shell inside the Frontastic sandbox and in the directory where your source code is mirrored to and from where it's run (/var/www/frontastic), so you can, for example, cd into your project folder. You should know the basics of Linux shell to work in here, a good overview can be found here: Basics of BASH for Beginners.

User/permissions

You're the user vagrant
vagrant also runs the Webserver so you shouldn't run into permission issues when editing files
If you still need to do something as root (for example, restart supervisor or read system logs), vagrant can sudo without a password
Just prefix some command that runs into permission issues like sudo some command and it will run

❗️
Please don't edit any system configuration files! Everything is automatically set up to mimic your production system as much as possible. Changing configuration manually voids support in case of an error.

That said, you can change anything for debugging or for learning purposes but be sure to destroy and re-create the Frontastic sandbox afterward to come back to a normal state.

Logs

All logs are stored in /var/log including all system environment logs. The most important ones are:

/var/log/nginx/error.log for webserver errors
/var/log/php.log for PHP problems

All Frontastic application logs reside in /var/log/frontastic, the structure is:

<customer>_<project> contains all logs for a specific project, for example:
- ssr.log everything about SSR
- dev/frontend.log logs from the Backend-for-Frontend (Symfony logs)
<customer>-<project>-yarn.log contains the webpack logs for browser compilations on the specific Project
replicator.log the logs of the Replicator
supervisord.log the supervisor logs (see below)

Build stack

We use ant to encapsulate all parts of the project build stack. You should use ant to run tasks in a standardized way.

The following commands work on the top-level (executing them for all projects plus the libraries) or inside a project directory (only for this project):

ant prepare ensures that all dependencies are in place, the database is updated, and so on
ant test executes all available automated tests

Symfony commands

Inside of every project directory, you can run bin/console to access many Backend-for-Frontend-related commands (Symfony command line). If you execute it without parameters, you'll be shown all the available commands (there are a lot!).

You won't need most of them, but sometimes there are edge-cases where the below could come in handy:

bin/console frontastic:clear clears all data from your project so that it will be re-applied from the Frontastic studio using the Replicator
bin/console frontastic:routes:rebuild rebuilds the routing based on the page folders in Frontastic
bin/console cache:clear will clear the backend cache which might be needed after certain backend code changes (for example, Symfony dependencies)
If you're working on the Backend-for-Frontend code, you might find the Symfony debugging commands helpful, too, which are all prefixed by debug:

Supervisor

The Frontastic API hub doesn't only consist of the Webserver, PHP Backend-for-Frontend, and some code files, but also some long-running process that handles tasks in the background. To maintain these tasks properly, we use a tool called Supervisord.

The central entry point for seeing the status and managing these commands is the command sudo supervisorctl (which needs to be started with sudo).

The most useful available sub-commands are:

sudo supervisorctl status to see all tasks maintained by Supervisor and if they're running, stopped, errored, and so on
sudo supervisorctl restart ['<task>'|all] to restart one or all tasks (advanced usage see the help of supervisorctl!)

The most important tasks running in Supervisor are:

replicator the Replicator that pulls changes from the Frontastic studio
...server-run... the NodeJS running the compiled SSR build per project
...server-webpack... the webpack instance re-building the SSR build on change per project
...browser-webpack... the webpack instance for host-serving the browser assets (JS, CSS, …) per project

If any of these for the project you're working on is in a stopped or errored state, you should try to restart and look into the logs (see above) if this doesn't help.

MySQL

Frontastic uses MySQL to store the configuration (page folders, page versions, and so on) for projects. It's very unlikely that you'll need to look into this directly, but if you're curious...

To access MySQL you can run mysql -uroot -p on the shell and use the password root to gain access. This will open the MySQL interactive shell where you can run MySQL commands (close using <Ctrl>+<d>).

There's a database for each project and you can inspect those using:

show databases; to see all databases
use <database>; to switch to a certain database
show tables; to see all tables in that database
describe <table>; to see the schema of a certain table

Of course, you can use the regular SQL commands to look into tables and even change data.

❗️
Don't change any database content! This voids support in case of an error.

If you've changed the database content, you can get back to a clean state using the bin/console frontastic:clear (command) or even better by destroying your Frontastic sanbox and bringing up a new one.