platform: ch.rswk.platform

💬 Contact
- rswk.ch for my personal contact information
- Forum for issues/questions/requests
Links

Table of contents:

Overview
Software development life cycle
Platform
Tech stack
Guidelines
Contribute
Security

Overview

Mission

Provide a self-hostable FLOSS software development platform to develop, deploy and operate robust applications.

Built on open source and licensed under MPL 2.0.
Contains minimal abstractions, dependencies and lock in. No SaaS, AI and other cruft.
Covers the full software development life cycle.
Ships with all the essentials.

Getting started

TODO
reference playbooks

To just take a look at the code, clone the main repository using Fossil:

fossil clone https://dev.rswk.ch/fossil/platform

The ops repository contains the deployment units:

fossil clone https://dev.rswk.ch/fossil/platform-ops

Software development life cycle

TODO

Make it work, make it right, make it fast. -Kent Beck
The only way to go fast, is to go well. — Robert C. Martin
There are no solutions. There are only trade-offs. — Thomas Sowell
Principles behind the Agile Manifesto

Develop

TODO
develop: bootstrap dev workstation to publish binaries in artifact repository
build (npm ci, mvn, skip tests)
add dependency js, java
update dependencies dito. npm ci vs npm install
tools: watchdog, jenkins, nexus. CI, CD, trunk based development
dependency management
npm outdated
mvn versions:display-dependency-updates "-Dmaven.version.ignore=.*alpha.*,.*beta.*,.*-M.*,.*-proto.*"
mvn versions:display-plugin-updates -N "-Dmaven.version.ignore=.*alpha.*,.*beta.*,.*-M.*,.*-proto.*"
npm ls --all (--omit dev)
mvn dependency:tree
mvn buildplan:list
https://github.com/rfichtner/maven-survival-guide
jvm debugging with flight recorder/zmc (started with service), heap dumps/mat (via api or jcmd <pid> GC.heap_dump <file-path>)
tests: unit (junit, qunit), e2e (webdriver), deploy (provision), logging
bug tracking. seperate facts (found in version x) from plans (fixed in version y)

Deploy

TODO
deploy: install binaries on machine/server/client and run application
two phases: versioned and released modules in platform/deploy. customized and installable deployables in platform-ops
roll forward approach
playbooks, runbooks
deployment diagrams platform, blueprint https://pikchr.org/home/doc/trunk/doc/examples.md

Operate

TODO
operate: application connected to ops infra, incidents.
ops server, ops workstation
when adding app server, add rsyncd module, wg peer to ops server

Platform

Develop
- API
  - Request/response JSON over HTTP2
  - Publish/subscribe JSON over SSE
- Client
  - ECMAScript ES.Next
  - Progressive Single-page Web App
  - Based on Mithril and Bootstrap
- Server
  - Java 23 with Preview Features
  - Based on Guava Services, Jetty and SQLite
Deploy
- Automated, continuous deployment
- Customizable, reproducible deployment files
- JSON runbooks
Operate
- Automated, monitored duplicity backups
- Watchdog monitoring and automated deployments
- WireGuard VPN

Documentation

Framework
- Util
- Api
- Client
- Deploy
- Server
- Test
Deploy
- Shared
- App
- Dev
- Ops
Test

Tech stack

We are standing on the giant shoulders of other FLOSS software. Please consider supporting and funding these projects.

Develop

Client

Server

Tool

Operate

Tool

Providers

Guidelines

Code

Do
- Specify units with quantities
- Use brackets for control flow statements
- Use LF line separators and end every file with a line break
  - Exceptions are OS specific files, eg. PowerShell scripts
- Use spaces for indentation
- Fail fast using conditional failures
- Write expressive code and put effort into naming things. Comments are a last resort
- Use composition over inheritance
- Put things in ASCII order when in doubt about orderings things
- TODO Method names, eg. send(request) vs sendRequest(request)
- Follow SQL Style Guide
Don't
- Use AI generated code
- Have circular class/module/package dependencies
- Use greater-than signs >/>=. Write 0 < limit && limit <= 10 instead
- Use negation !. Write expression == false instead
- Use preincrement/postincrement operators i++. Write i = i + 1 instead
- Violate class/module/package boundaries. If A depends on B, then B must be written like it has no knowledge about A

Java

Do
- Write documentation using Markdown JavaDoc and Snippets
- Use Optional
  - See [1] [2]
- Use Records
- Use Structured Concurrency with Scoped Values and Virtual Threads, plus primitives like atomics, locks, and semaphores
- TODO Builder conventions

JavaScript

Do
- Place semicolons.
- Document using JSDoc.
Don't
- Let commas dangling.

Contribute

Contributions are welcome.

Plase contact me or post on the forum to discuss your planned contribution
See 2.0 Submitting Patches
Send me the patch/bundle via email

Security

If you have any concerns/recommendations with regards to how I handle personal data/security in my code, please contact me via email or ask for my Signal contact information.