frans

Frans is a simple file-sharing service intended to be ready for cloud native.

It took heavy inspiration from DownloadTicketService. You could also call it a more modern implementation of DownloadTicketService optimized for todays (2025) IT landscape.

Included features

• Create file shares and share them with others
• Create upload grants which allow others to upload their files to you
• Container/Cloud-Native focused architecture
• OpenID Connect authentication only
• OpenTelemetry included

The goal is to translate frans to the following languages:

• English
• German
• French
• Spanish
• Russian
• Simplified chinese
• Japanese
• Dutch
• Portuguese, Brazilian
• Czech
• Italian

Feel free to contribute or improve translations via Crowdin

Installation

Helm Chart

Frans comes with a Helm chart hosted via GitHub Container Registry. The helm chart is unopinionated about anything outside of frans and therefore doesn't install anything besides frans itself. This means that you will have to prepare a database server, OIDC provider and a SMTP Server beforehand.

Your values.yaml should at least include the following values to connect with these services:

db:
  # Database type to use. One of `postgres`, `mysql` or `sqlite3`
  type: postgres
  # Database host (file path in case of `sqlite3`)
  host: localhost # or frans.db for sqlite3
  # Database port
  port: 5432 # or 3306 for mysql
  # Database name
  name: frans
  # Database user
  user: frans
  # Database password (required for postgres and mysql)
  password: frans

oidc:
  issuer: https://your-oidc-provider
  client_id: your-client-id

smtp:
  server: smtp-server-host
  port: 25

# optional. settings with types such as lists or maps can only be set via this configMap
# which results in a frans.yaml config file
configMap: |
  trusted_proxies: ["192.168.31.68/32"]

After your preparations are done, simply run

helm install frans oci://ghcr.io/jvllmr/frans --values values.yaml

to install the helm chart.

For more values.yaml options, take a look inside the default values.yaml.

Docker Compose

See docker-compose.minimal.yaml for a minimal example.

Pre-compiled binaries

Take a look at Frans GitHub Releases for pre-compiled binaries for linux, macOS and windows!

Requirements

Database

frans supports three types of databases. PostgreSQL, mysql / mariadb and sqlite

Authentication

frans does not handle user management by itself, but rather uses OpenID Connect (OIDC) to delegate this task to an OIDC provider. One of the more well known open source examples for an OIDC provider is Keycloak which was initially developed by RedHat and has graduated to be a Cloud Native Computing Foundation (CNCF) project. Therefore, frans is optimized for usage with Keycloak. If you want to try your luck with another OIDC provider, I have a checklist ready for you. The used OIDC provider client needs to:

• be a public client (no client secret needed) with pkce challenges
• allow usage of refresh tokens
• have an end_session_endpoint

SMTP Server

frans requires a SMTP server to send mail notifications.

Configuration

frans supports configuration via a frans.yaml configuration file relative to its executable or via environment variables.

Configuration keys

See frans.defaults.yaml

Development

I always welcome contributions. Even the smaller ones.

Development requirements

The following tools are required to start with development on frans:

• golang installed
• pnpm installed: installation via corepack is preferred
• docker with docker compose v2 installed
• atlas installed: https://atlasgo.io/guides/evaluation/install

Start environment

After you have installed all requirements you can start the environment

Start services

pnpm services

This will start the services frans depends on for development purposes. It starts:

• a keycloak instance available under http://localhost:8080
• a smtp4dev instance available under http://localhost:5000
• an OpenObserve instance available under http://localhost:5080

Keycloak can be managed via the credentials admin/admin. OpenObserve can be accessed via [email protected]/ admin.

Frans authentication is managed via the dev realm.

Setup database

pnpm db:migrate

Start backend & client for development

# Start go backend in dev mode
pnpm dev:go
# Start client dev server
pnpm dev

After starting both development servers, frans is available under http://localhost:8081/files.

You can login via one of the following credentials:

• frans_admin/frans_admin: User with administration rights

Do changes to database

Everything for ent is generated from the contents of internal/ent/schema. After making your changes there, run the following to apply them correctly:

# generate new ent source
pnpm ent:generate

# create migration scripts for postgresql, mysql and sqlite3
pnpm db:diff

# apply migrations to development database
pnpm db:migrate

Create a new database entity

pnpm ent:new <entity name>

Build

pnpm build