CommaFeed Documentation

For a quick setup, use the latest-h2 image which includes an embedded H2 database. The application will be accessible at http://localhost:8082/.

### docker

`docker run --name commafeed --detach --publish 8082:8082 --restart unless-stopped --volume /path/to/commafeed/data:/commafeed/data --memory 256M athou/commafeed:latest-h2`

Use the following docker-compose.yml configuration to run CommaFeed with an embedded H2 database. Ensure you map a local directory to /commafeed/data to persist data.

services:
  commafeed:
    image: athou/commafeed:latest-h2
    restart: unless-stopped
    volumes:
      - ./data:/commafeed/data
    deploy:
      resources:
        limits:
          memory: 256M
    ports:
      - 8082:8082

For production or more control, use the latest-postgresql image. You must provide database connection details via environment variables. The example below sets up both CommaFeed and a PostgreSQL container.

services:
  commafeed:
    image: athou/commafeed:latest-postgresql
    restart: unless-stopped
    environment:
      - QUARKUS_DATASOURCE_JDBC_URL=jdbc:postgresql://postgresql:5432/commafeed
      - QUARKUS_DATASOURCE_USERNAME=commafeed
      - QUARKUS_DATASOURCE_PASSWORD=commafeed
    deploy:
      resources:
        limits:
          memory: 256M
    ports:
      - 8082:8082

  postgresql:
    image: postgres:latest
    restart: unless-stopped
    environment:
      POSTGRES_USER: commafeed
      POSTGRES_PASSWORD: commafeed
      POSTGRES_DB: commafeed
    volumes:
      - ./data:/var/lib/postgresql

Use the Maven wrapper to build the application. You can specify the database type and whether to compile to native code.

Available database profiles (-P): h2 (default), postgresql, mysql, mariadb. Native compilation: Use -Pnative (requires GraalVM or a container environment).

Build commands:

• Standard build: ./mvnw clean package [-P<database> [-Pnative]] [-DskipTests]
• To skip tests for faster builds, add -DskipTests.

Output locations:

• JVM package: commafeed-server/target/commafeed-<version>-<database>-jvm.zip
• Native executable: commafeed-server/target/commafeed-<version>-<database>-<platform>-<arch>-runner[.exe]

You can customize the look and feel of CommaFeed by adding CSS rules in the Admin settings page under the "Custom Code" tab.

To target specific elements, use CommaFeed's built-in class names (prefixed with a period, e.g., .cf-header) or standard HTML elements (e.g., article). If an element you want to style does not have a specific cf- class, use your browser's Inspector (F12) to find a parent element that does have a cf- class and use it as a starting point for your CSS selector.

To develop CommaFeed locally, you need to run both the backend and the frontend.

Backend

1. Open commafeed-server in a Java IDE (requires Lombok plugin).
2. Run ./mvnw quarkus:dev.

Frontend

1. Open commafeed-client in a JavaScript IDE.
2. Run npm install.
3. Run npm run dev.

Note: The frontend server runs at http://localhost:8082 and proxies requests to the backend on port 8083.

You can download precompiled packages from the release page.

• Native packages (linux-x86_64, linux-aarch_64, windows-x86_64): Contain an executable that can be run directly. Recommended for faster startup and lower memory usage.
• JVM package: A zip file containing .jar files. Requires a JRE and is started using java -jar quarkus-run.jar.

To limit memory usage for the jvm package, use the -Xmx parameter.

Hard limit example: To limit the JVM to 256MB:

java -Xmx256m -jar quarkus-run.jar

Dynamic sizing: To allow the JVM to release unused memory to the OS, use the following parameters:

-Xms20m -XX:+UseG1GC -XX:+UseStringDeduplication -XX:-ShrinkHeapInSteps -XX:G1PeriodicGCInterval=10000 -XX:-G1PeriodicGCInvokesConcurrent -XX:MinHeapFreeRatio=5 -XX:MaxHeapFreeRatio=10

While H2 is used by default (storing data in the data directory), you can use PostgreSQL, MySQL, or MariaDB by configuring the following properties:

• quarkus.datasource.jdbc.url
• quarkus.datasource.username
• quarkus.datasource.password

CommaFeed supports multiple configuration methods. The properties file is recommended to catch typos.

1. Properties file: Create a config/application.properties file relative to the working directory (use kebab-case keys).
2. Command line arguments: Prefix keys with -D (use kebab-case keys).
3. Environment variables: Use UPPER_CASE keys.
4. Dotenv file: Use a .env file in the working directory (use UPPER_CASE keys).