Hellen Suite is an application for managing hotels and similar businesses. It simplifies operational controls and administrative and management tasks.
The application is available as both a web application and a desktop application powered by NativePHP Desktop. It is currently under development and is not yet ready for production.
Website: hellensuite.com
- PHP 8.3 or later and Laravel 13.
- NativePHP Desktop 2 and Electron.
- Inertia 3 and Vue 3.
- Tailwind CSS 4 and Vite 8.
- SQLite.
- PHPUnit 12.
- PHP, Composer, and the extensions required by Laravel.
- Node.js and npm.
- SQLite.
- Platform build tools for working with Electron and generating native applications.
Clone the repository and run the following command from its root:
composer run setupThis command installs the Composer and npm dependencies, creates .env from .env.example, generates APP_KEY, runs the migrations, and builds the frontend.
Prepare the NativePHP and Electron dependencies:
php artisan app:native:install --no-interactioncomposer run devThis command starts the Laravel web server, Vite, and the development logs. The web database is located at database/database.sqlite.
Apply new migrations with:
php artisan migratecomposer run native:devThis command starts the Electron application and Vite. The main window configuration is located at app/Providers/NativeAppServiceProvider.php.
NativePHP uses its own database during native execution. Apply its migrations with:
php artisan native:migrate# Test suite
php artisan test --compact
# Format modified PHP code
vendor/bin/pint --dirty --format agent
# Frontend ESLint; applies fixes automatically
npm run lint
# Production frontend build
npm run buildThe Vite build downloads the fonts configured in vite.config.js, so it requires a network connection.
A desktop application is installed on devices outside the developer's control. The user's system must therefore be treated as a potentially hostile environment, and no secret included in the application bundle should be assumed to be inaccessible.
The following principles apply to Hellen Suite:
- Do not bundle passwords, tokens, private keys, or infrastructure credentials in
.envor the source code. - Generate unique keys for each installation on first run whenever possible instead of sharing one key among all users.
- Use a robust protocol such as OAuth2 for private APIs, with unique, high-entropy, short-lived tokens. NativePHP recommends an expiration time of less than 48 hours.
- Always use HTTPS when sending data between the application and external services.
- Encrypt user-provided API keys if they must be stored in files or the database, and decrypt them only when needed.
- Restrict file access to expected locations, primarily the
appdatadirectory, the user's home directory, and its subdirectories, using theStoragedisks provided by NativePHP. - Keep Laravel's CSRF and CORS protections enabled, and do not expose unnecessary routes or native actions.
NativePHP runs local servers to connect Laravel and Electron. Their communication uses authenticated HTTP requests with a dynamic key regenerated on every startup. Never bypass or replace this authentication, as doing so could allow other applications or websites to call the internal APIs.
NativePHP automatically applies the global PreventRegularBrowserAccess middleware to production builds. This middleware restricts route access to requests originating from the WebView that started the application.
The PHP process runs with the current user's permissions and can therefore access anything available to that user. Every operation involving files, processes, or system resources must be validated and restricted to the minimum required scope. Other installed software could also use the bundled PHP executable, so users should only install applications from trusted sources.
Before publishing, review cleanup_env_keys in config/nativephp.php and verify that it removes all credentials used exclusively during the build or publication process. This project removes GITHUB_*, AWS_*, AZURE_*, DO_SPACES_*, Apple credentials, and other sensitive values.
Read the complete NativePHP Desktop 2 security guide before distributing a release.
The build process packages Laravel, the frontend, Electron, and the required runtime into a distributable application. It targets one operating system at a time.
Before building a release:
- Run the tests and
npm run build. - Increment
NATIVEPHP_APP_VERSIONin.env. - Review the migrations because NativePHP only runs them on installed systems when the version changes.
- Configure the appropriate code signing for Windows or macOS.
- Test the installer on every target platform.
Build for the current platform and architecture:
php artisan native:buildBuild for a specific operating system:
php artisan native:build mac
php artisan native:build win
php artisan native:build linuxCross-compilation is not supported for every platform combination. Test artifacts on the operating system where they will be distributed. On macOS, the application must be signed and notarized to run correctly on other devices and receive automatic updates.
Hellen Suite uses the public barbosa89/hellen-suite repository as its publishing and update provider.
Add these variables to the local .env file:
NATIVEPHP_APP_VERSION=1.0.0
NATIVEPHP_UPDATER_ENABLED=true
NATIVEPHP_UPDATER_PROVIDER=github
GITHUB_OWNER=barbosa89
GITHUB_REPO=hellen-suite
GITHUB_PRIVATE=false
GITHUB_TOKEN=github_pat_REPLACE_WITH_THE_REAL_TOKEN
GITHUB_V_PREFIXED_TAG_NAME=true
GITHUB_CHANNEL=latest
GITHUB_RELEASE_TYPE=draftThe .env file is excluded from Git. Never add the real token to .env.example, config/nativephp.php, this README, or any other versioned file. NativePHP removes GITHUB_* variables from the .env file included in the final application bundle.
Because the repository is public, do not define GITHUB_AUTOUPDATE_TOKEN. Installed applications can access public releases without authentication; GITHUB_TOKEN only authorizes artifact uploads during publication.
Create a fine-grained personal access token with the following configuration:
| Field | Value |
|---|---|
| Token name | Hellen Suite NativePHP Publisher |
| Resource owner | barbosa89 |
| Repository access | Only select repositories |
| Selected repositories | hellen-suite |
| Contents | Read and write |
| Metadata | Read-only, assigned automatically |
Choose an expiration date, generate the token, and copy it immediately; GitHub only displays it once. Store it as GITHUB_TOKEN in the local .env file or as a CI secret.
Clear cached configuration after changing these variables:
php artisan config:clear- Increment
NATIVEPHP_APP_VERSION; for example, from1.0.0to1.1.0. - Run the tests, build the frontend, and test
php artisan native:build. - Create a draft release on GitHub.
- If use the
v-prefixed version as its tag; for version1.1.0, createv1.1.0. - Publish the artifacts for each platform with
native:publish. - Verify the attached artifacts and publish the release.
- Validate the update from an installation of the previous version.
php artisan native:publish
# Or specify the target operating system
php artisan native:publish mac
php artisan native:publish win
php artisan native:publish linuxRunning native:publish again while the release remains a draft updates its artifacts. Draft releases are unavailable to users and must be published after verification.
NativePHP Desktop may fail during native:publish with this message even when GITHUB_OWNER and GITHUB_REPO are correctly defined:
Cannot detect repository by .git/config. Please specify "repository" in the package.json.
This is a known NativePHP Desktop issue. Laravel reads NATIVEPHP_UPDATER_ENABLED=true from .env, but NativePHP does not pass that value to the Electron Builder process. Electron Builder consequently receives no publish configuration and tries to infer the repository from .git/config inside vendor/nativephp/desktop/resources/electron, where no Git repository exists.
Clear the Laravel configuration cache and provide the variable directly to the publishing process:
php artisan config:clear
# Current platform and architecture
NATIVEPHP_UPDATER_ENABLED=true php artisan native:publish
# Windows x64
NATIVEPHP_UPDATER_ENABLED=true php artisan native:publish win x64Do not fix this by adding repository to vendor/nativephp/desktop/resources/electron/package.json. Files inside vendor are dependency internals and any local change will be lost on the next Composer installation or update.
The upstream fix is for NativePHP's BuildCommand::getEnvironmentVariables() to pass the effective updater state to Electron Builder:
'NATIVEPHP_UPDATER_ENABLED' => config('nativephp.updater.enabled') ? 'true' : 'false',Publishing a Windows installer from an Apple Silicon Mac may fail with an error similar to:
Cannot spawn .../electron-builder/nsis-3.0.4.1/.../mac/makensis:
Error: spawn Unknown system error -86
macOS error -86 means that the executable uses an unsupported CPU architecture. Electron Builder's NSIS package includes an Intel x86_64 build of makensis, while Apple Silicon Macs run arm64. Rosetta 2 is therefore required to execute this tool during a Windows cross-build.
Install Rosetta using Apple's system updater and follow the prompts:
softwareupdate --install-rosettaVerify that the cached NSIS executable can run:
"$HOME/Library/Caches/electron-builder/nsis-3.0.4.1/nsis-3.0.4.1-1mx3n/mac/makensis" -VERSIONIt should print the NSIS version instead of bad CPU type in executable. Then retry the publication with the NativePHP updater workaround:
php artisan config:clear
NATIVEPHP_UPDATER_ENABLED=true php artisan native:publish win x64If the same error remains after Rosetta is installed, remove only the generated NSIS cache so Electron Builder can download it again:
rm -rf "$HOME/Library/Caches/electron-builder/nsis-3.0.4.1"Building and publishing from a Windows machine or Windows CI runner is the alternative that avoids cross-compilation and Rosetta entirely.
See NATIVEPHP_BUILD_PUBLICACION_ACTUALIZACIONES.md for the complete guide to signing, building, publishing, automatic updates, updater events, and migrations.