kutt

To run Kutt locally, you need Node.js (version 20 or above). The default database is SQLite, but you can optionally use Postgres, MySQL/MariaDB, or Redis for caching.

Follow these steps to set up the development environment:

1. Clone the repository or download the latest zip.
2. Install dependencies using npm install.
3. Initialize the database using npm run migrate.
4. Start the application in development mode with npm run dev or in production mode with npm start.

Note: When you first start the app, you will be prompted to create an admin account.

Kutt can be deployed using Docker Compose. Ensure Docker is installed, then use the appropriate configuration file from the root directory to start the service.

Available configurations:

• docker-compose.yml: Default setup using SQLite.
• docker-compose.sqlite-redis.yml: Uses SQLite and Redis (requires REDIS_ENABLED).
• docker-compose.postgres.yml: Uses Postgres and Redis (requires REDIS_ENABLED, DB_PASSWORD, DB_NAME, DB_USER).
• docker-compose.mariadb.yml: Uses MariaDB and Redis (requires REDIS_ENABLED, DB_PASSWORD, DB_NAME, DB_USER, DB_PORT).

The official image is available on Docker Hub as kutt/kutt.

docker compose -f <file_name> up

If you are running Kutt via Docker, you must ensure your /custom folder is accessible to the container.

1. Official Images: Ensure the /kutt/custom volume is mounted in your Docker configuration.
2. Copying Files: If you are not using a volume, you can copy your local custom folder into the running container using docker cp.
3. Restart: You must restart the Kutt server container after copying files or making changes for them to take effect.

Kutt is configured using environment variables. You can provide them directly or via a .env file. Most variables are optional, except for JWT_SECRET, which is required for production environments.

To use a file for a specific variable instead of a string, append _FILE to the variable name (e.g., JWT_SECRET_FILE=/path/to/secret_file).

For a full list of available configuration keys, refer to the .example.env file in the repository.

Kutt supports custom themes and assets by looking into specific directories. You can override default behavior by placing files in the custom/ directory:

• Images: /images maps to custom/images
• CSS: /css maps to custom/css
• Views: Handlebars templates in custom/views take precedence over default views in views/.

You can deploy Kutt using Docker Compose. The setup includes a server service that builds from the local context and exposes port 3000. It uses two persistent volumes: db_data_sqlite for the SQLite database and custom for custom configurations/assets.

services:
  server:
    build:
      context: .
    volumes:
       - db_data_sqlite:/var/lib/kutt
       - custom:/kutt/custom
    environment:
      DB_FILENAME: "/var/lib/kutt/data.sqlite"
    ports:
      - 3000:3000
volumes:
  db_data_sqlite:
  custom: