Deploying Frontend
Overview
The frontend of Cafe Variome V3 is built using Flutter, a cross-platform application framework developed by Google. During development, we aimed to deliver a consistent user experience across all supported platforms. However, due to certain limitations inherent to Flutter, there are some differences between the web version and other platform builds.
This document outlines those differences and provides guidance on how to compile and install the frontend. While we offer a pre-compiled release for the web platform, it's important to note that some parameters must be defined at compile time. As a result, it's not feasible to distribute a single pre-built release that meets all use cases. The sections below will walk you through compiling the frontend from source to suit your specific requirements.
The frontend of Cafe Variome V3 is made up of three applications: the admin interface, the record-level query interface, and the metadata query interface. Each can operate independently as a standalone app, or, on the web platform, where they can seamlessly redirect between one another and work together.
The admin interface is used for managing the system. It handles user accounts, data sources, and configuration settings.
The record-level query interface allows users to query data sources and retrieve individual records.
The metadata query interface is used to search and retrieve metadata about data sources.
Certain features, such as login and the landing page, are shared across all three applications.
Prerequisite
To compile the frontend, you will need:
Flutter SDK, 3.29.0 or above.
Compatible Dart SDK, Flutter usually manages this automatically. The Dart SDK used to develop this project is 3.7.0.
A working internet connection, as the Flutter SDK will download dependencies from the internet.
Minimum of 1 GB available memory, minimum of 2 GB available disk space.
Compiling the frontend
The flutter application is designed to work on web and desktop environment, including Windows, Linux and macOS. Before compiling, several configurations need to be changed:
The JSON file contains only six entries:
The backend URL specifies the backend server this frontend will interact with. The redirect URL should point to the callback.html file within the web app, while the silent redirect URL should point to callback-silent.html. When running the frontend as a desktop application rather than a web app, these URLs can technically be set to any value—provided the frontend, backend, and Keycloak configurations all align. However, it's still recommended to use a domain under your control to avoid potential credential leakage if the URLs point elsewhere. The admin, discover, and meta-discovery URLs specify the locations of the three web applications. These are not used in desktop mode, so they can be left unchanged in that case.
If you're deploying the web app under a sub-path, you’ll also need to update the contents of callback.html. The line:
Needs to be changed to:
You can make this change either before compiling, within the web directory, or after compilation in the root of the output directory (typically build/web).
For official documents on how to build and release Flutter apps, refer to Google Documents.
The web version of the frontend is the easiest to compile and is the recommended method for distributing a hosted system. No additional tools are required for web compilation. To build the web version, configure the project as described above, then run the following command from the root directory of the frontend:
If the web app is meant to be served under a subpath (e.g. https://www.mydomain.com/cv3/), the main JavaScript file must be loaded from that subpath. To inform the Flutter engine of this, add the following parameter:
Remember to modify the callback.html file as mentioned above.
To compile for Linux, you’ll need a Linux system with the necessary development headers, along with gcc and other required dependencies. It's recommended to run flutter doctor beforehand and resolve any reported issues. To build for Linux, run:
This will generate a directory containing the compiled release. The binary file can be found in build/linux/release/bundle. If you need to distribute the application, packaging it as an AppImage may be more convenient. Configuration files for this process are included in the repository and can be used with flutter_distributor to create the AppImage. Since these configuration files must be modified before compiling, no pre-compiled AppImage is provided. To create the AppImage, run:
Installing the frontend
After compiling, the frontend can then be installed, distributed or served.
Any HTTP server can serve the compiled web app. An example of Apache virtual host configuration is: