Skip to content

Configuration

Ushka uses a simple and clean TOML file for configuration, named ushka.toml. This file is the central place to manage your application's settings.

When you create a new project with ushka new, a default ushka.toml file is generated for you.

The ushka.toml File

Here is an example of a ushka.toml file with some common sections:

# Main application settings
[app]
name = "My Ushka App"
debug = true
secret_key = "a-very-long-and-secret-string-for-sessions"

# Web server settings
[server]
host = "127.0.0.1"
port = 8000

# Database configuration
[database]
url = "sqlite+aiosqlite:///ushka.db"

# List of installed apps
[apps]
installed = ["home", "products"]

Core Sections

[app]

This section contains the core settings for your application.

  • name (string): The name of your application.
  • debug (boolean): If true, enables debug mode. This provides more detailed error pages and enables features like auto-reloading. Should be false in production.
  • secret_key (string): A long, random string used for securely signing sessions. This should be kept secret.

[server]

This section configures the web server.

  • host (string): The IP address to bind the server to. 127.0.0.1 is only accessible from your local machine. Use 0.0.0.0 to make it accessible from other machines on your network.
  • port (integer): The port for the server to listen on.
  • workers (integer): The number of worker processes to run (only effective in production, not with ushka dev).

[apps]

This section manages your application modules.

  • installed (list of strings): A list of the app modules that Ushka should discover and load. Ushka will look for these in the apps/ directory.

Feature Sections

Many of Ushka's built-in features are configured in their own sections. For example:

  • [database]: Configures the database connection.
  • [static]: Configures static file serving.
  • [admin]: Configures the built-in admin panel.
  • [cache]: Configures the caching system.
  • [queue]: Configures the background task queue.
  • [pwa]: Configures Progressive Web App features.

Please see the documentation for each specific feature to learn about its available configuration options.

App-Specific Configuration

Sometimes, an app module needs its own specific configuration that doesn't belong in the main ushka.toml. You can create an app.toml file inside any app's directory (e.g., apps/products/app.toml).

The most common use for this is to define a URL prefix for all routes in that app.

Example apps/products/app.toml: 

[app]
name = "products"
prefix = "/api/products"

With this configuration, all routes defined in apps/products/views.py will be automatically prefixed with /api/products. For example, a get_all view function would be accessible at /api/products/all.

Ushka automatically loads these app.toml files for all apps listed in the [apps].installed list.