Setup a real project
This is an extended version of a Quickstart guideline. It's scope is understand better what do you need and how approach, into the real, to start a project.
Requirements and installing
In first, you need a compatible version ( minimum v20 ) of Node.js with npm.
Most process into Staxis (like update, versioning, etc) require a modern version of git installed.
Now, like the quickstart guideline, you need to have a folder for you project and install into it Staxis.
So, text into terminal npx @staxis/do -install and choose "local" to install in current directory or "folder" to an extenal target (no racommended).
Post install
In the installed project directory you have two important files to rename: hmac and keys. The first is hashed representations of the software layers and are intended to maintain a stable, locked state, thereby making it difficult to tamper with them during execution. The scond is an alternative of classic ENV and rappresent the keys to start, access and talk betweend diffrent layers.
-> Rename .hmac.example to .hmac
-> Change .keys.example in .keys (do not share your keys directly online).
Intall rolled profile or init a new layer pack
As you've probably already guessed, Staxis groups your scripts into folders called βpackages.β In a software application, there can be many of these packages; one for the file system, several more for web and HTTP communication, others for support, and so on.
Now⦠Whether these packages are available online or not, you can install them one by one: node project manager -> install and text the git repository or the right name (if is it an official packs)
but itβs important to know that you can reinstall them all at once, without having to install them one by one:
Download one of official roll pack here
Check the name of rollpack ".name.roll" was text good (if you download from git it is usally to remove the dots)
Open the terminal and node project manager -> unroll and text the "name" or .roll packaged file
The auto installer unroll/install everything you need to make that kind of job, also with optional feautures (it can ask to you what you prefer) and the basic of all configurations. Easy, no?
It's sure, you can generate your roll file or init a new custom layer... but you need a little bit of extra experience, it's all in this manual, in the specific pages of manager, take your time for now.
Protect the keys
Typically, when installing or initializing a layer package, Staxis itself prompts you to generate a secure SHA key for that layer.
Even though we have a secure Vault system to manage it, and even though obtaining a secret does not guarantee easy access to the layer, exposing the keys is not a good idea.
You have installed everything but you could have a serius dangerous problem. For local asset is more easy, but before a real deploy we strongly suggest to not share you software keys.
You have different ways to hidden or recreate it. Let me you suggest some example...
- Copy it by CLI:
Someone share the only officials keys for everone, and print it directly via CLI by the host platform options.
- Share by secrets:
Like before, someone share the keys, but via some gitlab/hub/other secrets.
For CI/CD, store the environment's keys in your deployment secret store and provision .keys in the application directory before Staxis starts. With GitLab, you can use a protected file-type CI/CD variable and copy the supplied file into place during deployment. Keep its contents out of job logs, caches, build artifacts, and browser bundles. Reuse the keys for that environment across deployments. Changing the HMAC key also requires updating the associated integrity records. See GitLab's file-type variables.
- Regenerate randomically:
Since the keys are required at startup, this is a possibility (note: we haven't tested it)
Open you .keys and change all layer key with a SET_KEY_HERE.
Then create .keys from its example with the following command. It generates an independent random key for each placeholder and writes the result directly to the new file. For exemple:
open/close snippet code
// WARN THIS IS NOT TESTED node -e "const fs = require('node:fs'); const { randomBytes } = require('node:crypto'); const template = fs.readFileSync('.keys.example', 'utf8'); const keys = template.replace(/SET_KEY_HERE/g, () => randomBytes(32).toString('hex')); fs.writeFileSync('.keys', keys, { flag: 'wx', mode: 0o600 });"
Run this once for a new environment. The command stops if .keys already exists. Keep that file private and excluded from version control. On Unix-like systems, the command creates it with owner-only permissions. On Windows, configure access through the file's permissions.
So... Any trick is good to not share your secrets.
Tips for Backend and Full-Stack Developers
Installation one of profiles provide starting stacks that you can inspect and adapt to your project.
- π Monolithic stack file .roll
A broad starting stack for a backend application with multiple services and integrations. - π Backend stack file .roll
A backend setup with supporting packs for common service requirements. - π HTTP application file .roll
A basic HTTP application with a static HTML builder.
All roll files do not rapresent a mandatory but a shortcut.
You can also build separate services with Staxis. Each service needs its own configuration and
defined communication with the others. A dedicated profile for that setup is currently unavailable.
Tips for Frontend Developers
For a frontend served by its own Node.js application, start with the frontend installation profile and choose the server adapter and view engine your project needs.
- π Frontend stack
A server adapter, such as Express, and a view engine, such as React, EJS, or a static builder. - Local development security
For trusted local UI work, you can create system-core/.security containing level=low-security. This disables HMAC and Guardian checks. Use max-security for deployment and review the permissions required by your packs. - Development configuration
Set the following options inside engineopt in config.js, with logLayered inside its existing audit object.fastload: true, showlogo: false, cleanafter: true, // Inside engineopt.audit: logLayered: false
Launch the Project
Open a terminal in the project directory and run node project start. Continue through the manual for configuration and pack-specific instructions.
Thank you for choosing Staxis.