Ligoj ligoj

Ligoj

The open-source project portal. One place for the tools, access rights, health and cloud costs of every project.

Quick start · Screenshots · CLI · Plugins · Deployment · Documentation

Why Ligoj?

Each project uses a build server, a quality gate, a registry, a cloud account and an identity directory. Ligoj connects them, so teams and administrators work from one portal instead of a dozen consoles.


Projects and subscriptions	Each project subscribes to tool instances. Their health and key metrics come together on one dashboard.
Everything is a plugin	Tools, identity providers and features are plugins, installed and updated at runtime, with code signature checks.
Security built in	RBAC with regex-based UI and API rules, delegated administration, API tokens, OAuth2/OIDC login, multi-factor authentication and an audit trail.
Cloud cost management	Provisioning plugins bring catalog-aware cost estimation and optimization to each project.
API-first	Every feature is a REST endpoint, browsable through the OpenAPI explorer and scriptable with the CLI.
Modern and self-hosted	A Vue 3 and Vuetify 4 interface with dark mode, English and French, on a Java 25 and Spring Boot 4 API, shipped as Docker images and a Helm chart.

Screenshots

_{Project view: the subscribed tools and their live metrics}	_{Plugin manager: install, update and verify signatures}
_{Project list: search and manage every project}	_{Dark mode: several color themes and styles are built in}

Mobile view

_{Screenshots use fictional projects and sample tool data.}

Quick start

You need Podman with podman-compose, or Docker Compose. This starts the published images with PostgreSQL:

git clone https://github.com/ligoj/ligoj.git && cd ligoj

cat > .env <<EOF
LIGOJ_REGISTRY=docker.io/
LIGOJ_VERSION=5.0.2
EOF

podman compose -p ligoj -f compose.yml -f compose-override.yml up -d

Open http://localhost:8080/ligoj and sign in as ligoj-admin with the password ligoj-admin. A regular user, ligoj-user, is also created.

Warning

This setup is for evaluation only. The default identity plugin accepts any password, which the app bar flags as "Unsecured login". Before production, see Going to production.

Plugins, logs and the database persist in the named volumes ligoj-home and ligoj-db-data. To keep them in host directories instead, see Persistent Ligoj home.

To build the images from source instead, add --build to the last command. See Building the Docker images.

CLI reference

The ligoj CLI drives the REST API from a terminal or a pipeline. It needs Python 3.11 or later.

uv tool install ligoj-cli        # or: pipx install ligoj-cli, or: pip install ligoj-cli
mkdir -p ~/.ligoj

export LIGOJ_ENDPOINT=http://localhost:8080/ligoj
export LIGOJ_API_USER=ligoj-admin

ligoj session login --password ligoj-admin   # opens a temporary session
ligoj token create --save --id cli           # creates a durable API key and saves it
ligoj session logout                         # the API key takes over
ligoj session whoami

Everyday commands

ligoj info version                                                   # server version
ligoj -o text project list                                           # global options come first
ligoj project create --pkey demo --name "Demo" --team-leader ligoj-admin
ligoj plugin list
ligoj plugin install --id plugin-qa                                  # install parents first
ligoj plugin install --id plugin-qa-sonarqube
ligoj plugin restart                                                 # loads the new plugins
ligoj subscription list
ligoj cache invalidate --id nodes

Commands

Area	Command	Actions
Access	`session`	`login` `logout` `whoami` `get`
	`token`	`create` `list` `get` `delete` `purge` `purge-all`
	`user`	`list` `get` `upsert` `delete`
	`role`	`list` `get` `create` `delete`
Projects	`project`	`list` `get` `create` `delete`
	`subscription`	`list` `get` `create` `delete` `status` `refresh`
Platform	`info`	`version` `status` `all` `api`
	`plugin`	`list` `install` `upload` `javadoc` `restart`
	`node`	`list` `get` `status` `create` `upsert` `delete`
	`configuration`	`get` `set` `delete`
	`cache`	`list` `get` `invalidate`
	`hook`	`list` `get` `upsert` `delete`
	`file`	`get` `put` `delete`
Identity	`id:user`	`create` `get` `list` `delete` `reset-password` `add` `remove`
	`id:group`	`create` `import` `get` `list` `delete`
	`id:scope` `id:ou` `id:delegate-node` `id:delegate-org`	Scopes, organizational units and delegation
Cloud costs	`prov:quote`	`get` `locations` `refresh` `refresh-cost` `update`
	`prov:instance` `prov:database` `prov:container` `prov:function` `prov:storage`	Quote resources
	`prov:support` `prov:usage` `prov:budget` `prov:optimizer` `prov:tag` `prov:catalog` `prov:upload`	Quote settings, price catalogs and CSV upload
Tools	`build:job` `jenkins` `sonar` `nexus` `harbor` `gitlab` `argocd` `alfresco`	Tool-specific operations
Automation	`bootstrap`	`init` `create-project` `delete-project` `create-nested-project` `create-roles` `delete-roles` `welcome-user`
	`dev`	A local development environment with its backing services
	`update`	Update the CLI

Global options

Option	Environment variable	Purpose
`-e`, `--endpoint`	`LIGOJ_ENDPOINT`	Ligoj URL
`-u`, `--api-user`	`LIGOJ_API_USER`	User name
`--api-key`	`LIGOJ_API_KEY`	API key
`--profile`	`LIGOJ_PROFILE`	A profile from `~/.ligoj/config` and `~/.ligoj/credentials`
`-o`, `--output`	`LIGOJ_OUTPUT`	`json`, `text` or `table`
`-k`, `--insecure`		Allow insecure TLS connections
`-G`, `--debug`		Debug logs

Each level has its own help, for example ligoj project create -h. The full reference is in the CLI documentation, and instance setup with the CLI is in Configuration with CLI.

Plugins

These plugins are published on Maven Central for the 5.x generation, and were loaded together on API 5.0.2:

Domain	Plugins
Identity	`plugin-id` · `plugin-id-ldap` · `plugin-id-sql` · `plugin-id-cognito` · `plugin-iam-node` · `plugin-password`
Build	`plugin-build` · `plugin-build-jenkins`
Code quality	`plugin-qa` · `plugin-qa-sonarqube`
Registry	`plugin-registry` · `plugin-registry-nexus`
Cloud costs	`plugin-prov` · `plugin-prov-aws`
Mail	`plugin-mail` · `plugin-mail-smtp`
Interface	`plugin-ui`, embedded in the API

Important

A tool plugin needs its parent plugin: plugin-qa-sonarqube needs plugin-qa. Install the parent first: a plugin with a missing parent is not loaded, and an error in the API log names what is missing.

Older generations of other plugins exist on Maven Central, and not all of them run on 5.x. To write your own, see Creating your own plugin and plugin-api.

Deployment

flowchart LR
    B([Browser]) -->|":8080"| UI["<b>ligoj-ui</b><br/>Vue app, session, REST proxy"]
    C([ligoj CLI]) -->|":8080"| UI
    UI -->|":8081"| API["<b>ligoj-api</b><br/>REST API, Java plugins"]
    API --> DB[("PostgreSQL<br/>or MySQL")]
    API --> T["Your tools<br/>LDAP, Jenkins, SonarQube, AWS..."]

Target	Start with
Docker or Podman Compose	Deployment with Docker Compose · Compose variables · MySQL or PostgreSQL
Kubernetes	`helm install ligoj ./charts/ligoj` · Helm installation · chart reference
Containers	Docker execution · `ligoj/ligoj-api` · `ligoj/ligoj-ui`

Going to production

Identity: replace the default identity plugin with a real provider, such as plugin-id with plugin-id-ldap, plugin-id-sql or plugin-id-cognito, or use OAuth2/OIDC login.
Encryption: replace the default app.crypto.password=public with your own secret through LIGOJ_API_CRYPTO and LIGOJ_WEB_CRYPTO. See Encryption.
Database: set your own LIGOJ_DB_PASSWORD, or use an existing database server.
Administrator: review the initial user settings.
Network: expose only ligoj-ui, behind TLS. ligoj-api must stay internal.

Documentation

The full documentation is in DOC.md.

Topic	Read
Concepts	Architecture · Features · Subscriptions
Security	Security and RBAC · Login modes · API tokens · Audit
Plugins	Plugin management · Installation · Code signing · Extension points
Operations	Application properties · Logs · Management endpoints and SBOM · Troubleshooting
Integration	REST API and OpenAPI · Hooks · Files · Branding the UI
Development	Backend · Frontend with Vite · Interface architecture · Packaging · Dev setup wiki
Compatibility	Databases and Java
Releases	Changelog · Version française · GitHub releases

Contributing

Bug reports and pull requests are welcome through GitHub issues. Please read the code of conduct and the development guidelines.

License

MIT ·

Navigation Menu