Project operations

1. Docker Compose

The main workflow requires Docker Desktop or Docker Engine with Compose. No host GNU Octave installation is needed: GNU Octave 11.3.0 runs inside the container.

From the repository root, run:

docker compose up --build

The equivalent older standalone Compose command is:

docker-compose up --build

Once the containers are ready, open http://127.0.0.1:8080. Create a model or load a TXT file, then click Run analysis. The interface shows analysis status and logs, and the finished result opens automatically in the postprocessor.

Stop the application with Ctrl+C in its terminal. Remove the created containers and network with:

docker compose down

2. Settings and limits

Only Nginx is published on the loopback interface. FastAPI and Octave are accessible only within the Compose network. The API accepts models, not arbitrary scripts, paths or Octave expressions. One worker runs analyses sequentially; other accepted jobs wait in a queue.

For example, start the application on port 8090 in PowerShell:

$env:MKEF_PORT = "8090"
docker compose up --build

3. Project verification

Container smoke test

With the stack running, execute from the repository root:

./scripts/compose_smoke_test.ps1

Python and Octave integration tests

docker build --target test -t mkef-solver-test -f docker/solver.Dockerfile .
docker run --rm mkef-solver-test

Browser application tests

Open these files from disk preprocessor/tests/index.html, postprocessor/tests/index.html and shared/tests/index.html. A successful result contains only PASS lines and a final passed-check count.

If your browser blocks local scripts, run from the repository root:

python -m http.server 8000

Then open preprocessor tests, postprocessor tests and shared tests. Stop the server with Ctrl+C.

Local numerical-core tests and GNU Octave requirements are described in chapter 12.

4. Offline web interfaces

preprocessor/index.html and postprocessor/index.html can be opened directly from disk. This mode supports creating and editing TXT models and viewing saved JSON results. Running an analysis from the preprocessor requires the container API.

Preprocessor

Create nodes and elements on the SVG canvas; edit exact coordinates, properties, supports and loads in tables. Open a TXT file with Open TXT or drag it into the window. Configure the coordinate grid, its size and snapping step in the Canvas settings panel; selected-node coordinates are also available in the Selection.

The chosen analysis type is saved in section analysis. Its syntax and old-file compatibility rules are in the format description.

Postprocessor and units

The postprocessor does not convert numbers. Labels come from metadata.units in the exported JSON and must match the input model’s consistent unit system. A normalized eigenvector has arbitrary amplitude and is not a physical displacement.

5. Repository structure

6. Where to find more information

• input format, units, elements, supports and loads;
• static analysis and the static postprocessor view;
• modal analysis and mode animation;
• transient analysis, time histories and spectrum;
• local element forces, strains and stresses;
• architecture, sparse assembly and verification map;
• complete Mario Paz numerical example;
• working directly in GNU Octave without Docker.

Uniform-load checks

The complete suite run_octave_tests includes test_element_loads. Container API tests run CaseUniformFrame through actual GNU Octave. Browser suites are available at preprocessor/tests/, postprocessor/tests/ and shared/tests/.

For automated interface checks, install Playwright in the development environment, export CaseUniformFrame to output/uniform-result.json and run node scripts/test_browser.cjs. If needed, the variable MKEF_PLAYWRIGHT_MODULE specifies the installed Playwright module path. The script checks cascading deletion, Undo/Redo and JSON v2 reading, and saves screenshots in output.

Public VPS and local workflows

Labs run only in a locally installed GNU Octave without Docker: setup; addpath(fullfile(pwd, 'reference', 'examples')); results = run_reference_examples();. The local Docker web application is a separate workflow; its existing settings and commands remain unchanged.

Public deployment uses the same images with an additional compose.public.yaml. Build from source locally; this repository does not publish images. First prepare .env and networks using public-deployment.md:

# First prepare private .env and shared networks: see public-deployment.md
docker compose -f compose.yaml -f compose.public.yaml -f compose.caddy.yaml config --quiet
docker compose -f compose.yaml -f compose.public.yaml -f compose.caddy.yaml up --build -d

Do not use compose.release.yaml or upstream MKE-F images for this site. Build web and solver from the same reviewed MKE-F-PUBLIC commit. Source releases are published in the private GitHub repository; select a release tag (initially v0.8.3) and record its SHA. The version is stored in VERSION, notes in RELEASES.md, and publishing instructions in DEVGUIDE.md. The public Compose file lists MKEF_PUBLIC_* settings and MKEF_HTTP_* request budgets.

The initial profile has two workers, eight active jobs, a 180-second queue timeout and a 60-second run timeout; 200 nodes, 400 elements, 800 DOFs (300 for modal analysis), 5000 steps and 100000 DOF × samples. Support, load, release and MPC records are also bounded. Current limits are available at /api/v1/capabilities; verify that the mode is public.

On Ubuntu use the shared Caddy project in BGModeller, distinct application secrets and private networks as described in public-deployment.md. Caddy obtains and renews HTTPS certificates automatically. Neither web nor solver publishes ports; internal Nginx serves assets and buffers uploads. The API verifies the proxy and admits requests before reading bodies. No CDN is assumed. One API process owns the queue and HTTP counters.

/jobs is temporary memory-backed storage, separate from the repository's output. Public inputs, results and job metadata expire five minutes after completion; local retention stays at 24 hours. Expired API requests return 404 and cleanup deletes files while allowing already-started downloads to finish. Container shutdown loses data earlier. Anyone with a result link can view it; cancellation requires the creating browser's secret, without registration.

Save the model TXT and result JSON. A loaded result remains downloadable from its open page after the server copy expires. Saved JSON opens without recalculation; saved TXT can be submitted again.

Before opening access, load-test the target VPS (provisionally 4 vCPU / 8 GB) and verify HTTPS and closed ports externally. API, two Octave processes and temporary files share a 6 GB container limit. Exited containers restart, but an unhealthy status alone does not trigger restart. See public-deployment.md for acceptance checks.