agentleFS
ls1intumls1intum/Artemis/skills/local-setup/SKILL.md

local-setup

Skill829 starsChanged 3 years agoMITView on GitHub

Set up or troubleshoot a local Artemis server and client development environment.

  • Installs packages

The file

We split this skill into the rules it gives an agent

2 rules. About 0 are common, 0 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Run corepack enable once. It activates the exact pnpm version the repository pins, which avoids a whole category of lockfile arguments.

    line 17
  2. Very specific:

    Use --frozen-lockfile unless you are deliberately changing dependencies, in which case plain pnpm install lets the lockfile update.

    line 43

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Get Artemis running locally

Prerequisites

ToolVersionNote
JDK25Pinned by the Gradle toolchain
Node24.21.0 or newerPinned in gradle.properties and package.json
pnpm12.15.0Pinned by the packageManager field; activate with corepack enable
DockercurrentRequired for the database and for server tests

Run corepack enable once. It activates the exact pnpm version the repository pins, which avoids a whole category of lockfile arguments.

Python helper tools install with python -m pip install --require-hashes -r requirements.txt in a virtual environment. Change requirements.in and regenerate locks with supporting_scripts/update_python_dependency_locks.sh; see documentation/docs/developer/builds-and-dependencies.mdx for updates and supported Python versions. The Ubuntu LocalCI k3s and Helm installer URLs, SHA-256 hashes and release versions must be updated together. Never replace the verified download with a download piped into a shell.

On macOS, Homebrew's openjdk@25 is keg-only, so nothing finds it after installation. Register it with the system once, rather than exporting JAVA_HOME in every shell:

brew install openjdk@25
sudo ln -sfn "$(brew --prefix openjdk@25)/libexec/openjdk.jdk" /Library/Java/JavaVirtualMachines/openjdk-25.jdk
./gradlew --version   # confirms Gradle picks up JVM 25

Install dependencies

corepack enable
pnpm install --frozen-lockfile

Use --frozen-lockfile unless you are deliberately changing dependencies, in which case plain pnpm install lets the lockfile update.

Two ways to run

Full stack in one command. Slower to restart, fine for server work where the client rarely changes:

./gradlew bootRun

Server and client separately. This is what you want for client work, because the Angular dev server does hot module replacement:

./gradlew bootRun -x webapp   # terminal 1: server only
pnpm start                    # terminal 2: Angular dev server with HMR

The client is then on port 9000 and the server on 8080.

Expect roughly thirty seconds of startup. That is the normal cold start, not a symptom. Disabling feature modules barely changes it, because most of it is Spring context work that lazy initialisation already defers.

Test users

The users you log in as locally are seeded by Liquibase, not created by a script. src/main/resources/config/liquibase/e2e/users.csv provides exactly seven, each with its login as the password:

LoginRole in the Playwright suite
artemis_adminadmin
artemis_test_user_1studentOne
artemis_test_user_2studentTwo
artemis_test_user_3studentThree
artemis_test_user_4studentFour
artemis_test_user_6tutor
artemis_test_user_16instructor

The numbering is deliberately not contiguous, so do not assume artemis_test_user_5 exists. The names are exported from src/test/playwright/support/users.ts. A database that has run the migrations already has these users, and src/test/playwright/init/importUsers.spec.ts verifies them rather than creating anything.

supporting_scripts/create_test_users.sh is a different, much smaller thing: it creates three users, aa01aaa through aa03aaa, through the admin REST API, and it takes the server as a required argument:

supporting_scripts/create_test_users.sh localhost:8080

Called without that argument it POSTs to http:// and silently does nothing. You do not need it for normal development or for Playwright.

Seeing outgoing mail

Artemis only sends mail when it is configured to. To view what it would send, run a local Mailpit alongside the server and point the mail configuration at it. See documentation/docs/developer/mailpit-setup.mdx.

When it will not start

"Configure meaningful values for info.operatorName ...". A core node under the prod profile refuses to start without info.operatorName, info.operatorAdminName and info.universityName, even with telemetry off, unless info.testServer is true. Development profiles never hit it; locally it comes from the Artemis (Server, Prod, LocalCI) run configuration or a prod Docker setup. Set all three in application-local.yml (empty and template values such as Admin, Your University or <name> are rejected), or set info.testServer: true.

"Unable to determine Dialect". The Spring profile set does not include a database profile, or an autoconfigure.exclude is replacing rather than merging the expected exclusions.

The server logs "Started ArtemisApp" but then shuts down. A Spring Boot and Spring Cloud version mismatch does exactly this. The two are coupled: a Boot minor bump needs the matching Cloud release train. Both are pinned in gradle.properties.

Aggregate health reports DOWN. This does not by itself mean the server is broken. Check the readiness and liveness endpoints and look for "Started ArtemisApp" in the log; a single unconfigured optional integration pulls the aggregate down.

Port already in use. ./supporting_scripts/e2e/run-e2e-tests-local-fast.sh --stop frees 8080 and 9000 by killing the server and client. The LocalVC SSH listener on 7921 lives inside the server JVM, so it goes with it.

Running things

./gradlew test -x webapp        # server tests, needs Docker
pnpm run vitest                 # client tests, watch mode
./supporting_scripts/e2e/run-e2e-tests-local-fast.sh   # E2E, brings up everything it needs
pnpm run lint                   # client lint
./gradlew spotlessApply         # fix Java formatting

Full setup documentation, including IDE configuration and the optional integrations: documentation/docs/developer/setup.mdx.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.