Service: Ghostfolio - EyevinnOSC/community GitHub Wiki

Ghostfolio

Ghostfolio (serviceId ghostfolio-ghostfolio) is an open source (AGPL-3.0) wealth management app for tracking net worth across stocks, ETFs and cryptocurrencies. In Eyevinn Open Source Cloud (OSC) it is a long-running service instance. It stores its data in PostgreSQL and uses a Redis-compatible cache (Valkey), so the Ghostfolio instance itself is stateless. Source: ghostfolio/ghostfolio.

What it can do

  • Create and manage transactions across multiple accounts and view performance over common time ranges, including dividends and total return.
  • Import and export portfolio data.
  • Show charts and static analysis to spot potential portfolio risks.
  • Run as a mobile-first PWA and expose a public API (health checks, import/export, an experimental public portfolio view).

Creating an instance

Create the dependencies first and confirm they are running:

  1. PostgreSQL (birme-osc-postgresql, see Service: PostgreSQL). Set PostgresPassword (as a secret reference) and PostgresDb to ghostfolio; leave the user at its default (postgres). Read the internal cluster address with describe-service-instance; it has the form <tenant>-<name>.birme-osc-postgresql.svc.cluster.local. The database URL is postgresql://postgres:<password>@<tenant>-<name>.birme-osc-postgresql.svc.cluster.local:5432/ghostfolio. Ghostfolio creates and migrates the schema automatically on every start.
  2. Valkey (valkey-io-valkey, see Service: Valkey). Its Password option is optional. The instance details show an external address, so use the internal address <tenant>-<name>.valkey-io-valkey.svc.cluster.local, port 6379.

Generate two long random strings (for example openssl rand -hex 32 twice) and store the values as service secrets with create-service-secret (serviceId: "ghostfolio-ghostfolio"):

  • ghostdburl: the PostgreSQL URL
  • ghostsalt: first random string (becomes AccessTokenSalt)
  • ghostjwt: second random string (becomes JwtSecretKey)
  • ghostredispw: the Valkey password, only if you set one

Then call create-service-instance with serviceId: "ghostfolio-ghostfolio". The instance name must be alphanumeric and at most 20 characters.

{
  "name": "myfolio",
  "DatabaseUrl": "{{secrets.ghostdburl}}",
  "RedisHost": "<tenant>-<valkey-name>.valkey-io-valkey.svc.cluster.local",
  "RedisPort": "6379",
  "RedisPassword": "{{secrets.ghostredispw}}",
  "AccessTokenSalt": "{{secrets.ghostsalt}}",
  "JwtSecretKey": "{{secrets.ghostjwt}}"
}

Omit RedisPassword if the Valkey instance has no password. Wait with wait-for-service-ready; the first start takes a minute or two while the database is set up.

Options

Option Required Type Meaning
name Yes string Name of the instance. Alphanumeric/underscore only, at most 20 characters.
DatabaseUrl Yes string, sensitive PostgreSQL connection URL, for example postgresql://user:password@host:5432/dbname. Feeds DATABASE_URL. The schema is migrated and seeded automatically on every start. The OSC entrypoint adds connect_timeout=300 if the URL does not set it.
RedisHost Yes string Host name of the Redis or Valkey server, for example the internal cluster name of an OSC Valkey instance. Feeds REDIS_HOST.
RedisPort No string Port of the Redis or Valkey server. Defaults to 6379. Feeds REDIS_PORT.
RedisPassword No string, sensitive Password of the Redis or Valkey server (for OSC Valkey, its Password option). Leave empty if there is none. Feeds REDIS_PASSWORD.
AccessTokenSalt Yes string, sensitive Long random string used to derive users' security tokens. Feeds ACCESS_TOKEN_SALT. Must stay the same across restarts: if it changes, existing security tokens stop working and users are locked out.
JwtSecretKey Yes string, sensitive Long random string used to sign login tokens (JWT). Feeds JWT_SECRET_KEY. Keep it secret.

The four sensitive options should be passed as {{secrets.NAME}} references; a reference must be the entire field value. Overwriting a secret does not restart a running instance. Other Ghostfolio settings (data provider API keys, optional features) are not exposed as options. The default market data source is Yahoo Finance, which needs no key.

Using the instance

First sign-in

Open the instance URL while signed in to OSC and click "Get Started". Ghostfolio creates an anonymous account and shows a security token once; save it, as you use it to sign in later. The first account created on a fresh instance gets the admin role, so create your own account right after the instance starts.

Limitations

  • Behind the OSC sign-in only: the OSC authentication gate protects every path except /, which redirects to a protected page. The whole UI and the API require an OSC sign-in, so apps outside OSC cannot reach the API. In the first minute or two after creating an instance, some requests can get an odd 404 before the access rules settle; wait and retry.
  • Never change AccessTokenSalt after accounts exist.
  • The first account created is the admin.
  • No backup is configured. Back up the PostgreSQL instance, which holds all portfolio data.
  • Personal finance data is sensitive; protect your OSC account.
  • Importing activities, data providers, OIDC or Google sign-in, a Valkey password, TLS to PostgreSQL and upgrades have not been verified.

Resources

⚠️ **GitHub.com Fallback** ⚠️