This guide walks you through unpacking the Aussom-Server developer
zip into a working directory, laying down the default config and a
sample app with the -i install option, and tuning config.yaml
and applications.yaml for your own work. It also covers what to
add to .gitignore if you are dropping the server into an existing
git repository.
The developer zip is the right starting point for local development
and small single-host deployments where you control the JVM. For
production container deployments use the Docker bundle and follow
design/docs/docker-usage.md instead.
The download is named aussom-server-<version>.zip and unpacks
into a single directory:
aussom-server-<version>/
aussom-server.jar
AUSSOM-SERVER-LICENSE.txt
AUSSOM-SERVER-LICENSE-EXCEPTION.txt
AUSSOM-SERVER-README.md
aussom-server.jar is the fat JAR. Everything else is reference
material. Nothing in the zip is generated yet; running -i fills
in the rest of the layout.
java -version.You have two reasonable choices.
mkdir my-server
cd my-server
unzip /path/to/aussom-server-<version>.zip
mv aussom-server-<version>/* .
rmdir aussom-server-<version>
Use this when the server is its own thing and the apps you intend to run are kept in separate repos or directories.
cd /path/to/your-repo
unzip /path/to/aussom-server-<version>.zip
mv aussom-server-<version>/* .
rmdir aussom-server-<version>
Use this when your repo already holds the Aussom apps and you want
the server to live alongside them. This keeps start-server.sh,
config.yaml, and apps/ all relative to the repo root, so a
single sh start-server.sh from anywhere on your team boots a
predictable server.
You will want to gitignore the server binaries themselves so the repo stays source-only. See "Using inside a git repo" below.
From the directory you just extracted into:
java -jar aussom-server.jar -i
-i (install) is idempotent: it creates anything missing and skips
anything already on disk. Running it twice does no harm.
What gets created:
config.yaml (with freshly-generated keys)
start-server.sh (chmod +x, with the key baked in)
apps/
applications.yaml (lists which apps are enabled)
helloworld/ (sample app)
helloworld.aus
app_data/templates/index.html
public/css/helloworld.css
logs/ (empty - server logs land here)
lib/ (empty - drop runtime JARs here)
The two generated secrets in config.yaml:
key - the encryption key the server uses to encrypt and decrypt
secure properties. Treat it like a password.admin.server.clients[0].apiKey - the X-API-KEY header value
for the bundled admin client. Required for every admin endpoint
except /Admin/health.Both are written to stdout once during install. Save them somewhere secure if you plan to drive the admin API from another machine.
After install:
sh start-server.sh
The server runs in the foreground. Ctrl-C to stop. The sample app
is at http://localhost:8081/helloworld/.
config.yaml is the server-wide configuration file. The most
common edits during early setup:
local:
server:
port: 8081 # main HTTP server (apps live here)
admin:
server:
port: 8091 # admin endpoints (/Admin/...)
Change either if you have a port conflict. Bind to 127.0.0.1
under host: if you do not want the server reachable from other
machines on your network.
local:
server:
appDir: "apps"
Where the server looks for app sources. Relative paths are resolved
against the directory start-server.sh runs from. Override only if
you want the apps tree to live somewhere other than ./apps/.
local:
server:
logDir: "logs"
logLevel: "info" # trace | debug | info | warn | error
debugLogging: false # true also mirrors all logs to stdout
Set debugLogging: true while you are iterating - it tees every
log line to your terminal so you do not have to tail the log file.
local:
server:
cache:
maxAge: 0
byExtension:
html: 0
css: 0
js: 0
png: 86400
jpg: 86400
jpeg: 86400
maxAge is the default Cache-Control: public, max-age=<seconds>
value. byExtension overrides it per file extension. The defaults
keep developer-edited files (html, css, js) at zero so a refresh
always fetches fresh bytes. Bump to longer values for production.
admin:
server:
clients:
- name: "localhost"
description: "Connection from localhost."
apiKey: "<generated>"
permissions: "all"
allowedIps: "127.0.0.1"
Add a block per client that needs admin access. permissions
options: all, list, reload, webhook. Use allowedIps to
restrict by source address (comma-delimited).
admin:
server:
webhookScript: "apps/webhook.sh"
Uncomment and point at a script you control to enable
POST /Admin/webhook. Without this set, the endpoint returns 503.
The script runs with a set of AUSSOM_WEBHOOK_* environment
variables - see design/webhook-design-doc.md.
apps/applications.yaml is the registry of which apps are loaded
and how. The default install registers the sample helloworld app.
Add an entry per app. Each entry is a dict with these keys:
applications:
- name: helloworld # required - URL prefix and dir name
appDirectory: helloworld # required - subdir under apps/
enabled: true # set false to skip loading
hostResources: true # serve files from publicHttpDirectory
publicHttpDirectory: public # subdir under appDirectory
hostDocEndpoint: true # /<name>/doc returns aussomdoc markdown
hostApiEndpoint: true # /<name>/api returns OpenAPI YAML
reloadOnFileChange: true # auto-reload when source files change
logLevel: info # per-app log level
apps/<yourapp>/<yourapp>.aus plus any
subfolders it needs (public/, app_data/templates/, etc.).applications.yaml mirroring the helloworld
entry. The name field becomes the URL prefix; routes are
/<name>/<functionName>.reloadOnFileChange: true so the
server picks up source changes automatically.reloadOnFileChange: true is great for development but reloads
on every save. Turn it off for production runs.hostResources: true plus a publicHttpDirectory is what makes
static files (HTML, CSS, JS, images) served at /<name>/<file>.hostDocEndpoint and hostApiEndpoint flags are off by
default in production templates - they expose internal API
shape, which is fine for local work and questionable on a public
host.If you extracted the zip into an existing repo, tell git to ignore
the server distribution itself plus everything -i generates with
secrets in it. A reasonable .gitignore block:
# Aussom-Server distribution files (ship the .zip, not the JAR)
aussom-server.jar
AUSSOM-SERVER-LICENSE.txt
AUSSOM-SERVER-LICENSE-EXCEPTION.txt
AUSSOM-SERVER-README.md
# Generated by 'aussom-server -i' - holds keys and absolute paths
config.yaml
start-server.sh
# Runtime
logs/
lib/
What to keep in version control:
apps/applications.yaml - the registry of apps that make up
your project.apps/<yourapp>/ - your actual code.What to keep out:
aussom-server.jar and the AUSSOM-SERVER-* files - they belong
in the release zip, not the source tree. Anyone cloning the repo
unpacks a fresh zip on their machine.config.yaml - holds the encryption key and the admin API key.
Each clone should run -i to get its own.start-server.sh - has the encryption key baked in and an
absolute path to the JAR that only matches the machine that ran
-i. Re-generated by -i on each clone.logs/ and lib/ - per-machine runtime state.A teammate cloning the repo bootstraps with the same two commands you used:
unzip /path/to/aussom-server-<version>.zip
mv aussom-server-<version>/* .
rmdir aussom-server-<version>
java -jar aussom-server.jar -i
sh start-server.sh
Their config.yaml and start-server.sh get fresh keys; the apps
under apps/<yourapp>/ come from the repo.
If everyone needs the same admin API client list, ports, or cache
settings, do not check config.yaml in. Instead, commit a
config.yaml.sample with placeholder keys (REPLACE_ME) and have
each developer cp config.yaml.sample config.yaml and paste in
their own values. This keeps secrets out of git while still
sharing the structural pieces.
java -jar aussom-server.jar -k # generate a fresh secure key
java -jar aussom-server.jar -e "..." # encrypt a string with the
# current key (for secure
# properties in config.yaml)
java -jar aussom-server.jar -v # version banner
java -jar aussom-server.jar -h # full flag list
java -jar aussom-server.jar -s # start (same as start-server.sh)
java -jar aussom-server.jar -d <file> # render aussomdoc for a file
java -jar aussom-server.jar -a # render OpenAPI for the current
# app config
-s reads config.yaml and apps/applications.yaml from the
current directory unless you pass -cf and -ad. The generated
start-server.sh already does this for you.
design/docs/docker-usage.md - the production container path,
with install.sh and upgrade.sh for managed deploys.design/docs/firebase-usage.md - server-side Firebase auth in
Aussom apps.design/docs/websocket-usage.md - writing @Websocket handlers.design/docs/oas-annotations.md - documenting your routes so the
/<app>/api endpoint produces useful OpenAPI.