Luminus-Template Documentation

You can stress test your Luminus application using Apache Benchmark (ab) and monitor resource usage using standard Java profiling tools.

Stress Testing: Run the following command to send 1000 requests with a concurrency of 10:

ab -c 10 -n 1000 http://127.0.0.1:3000/

Resource Monitoring: Attach jconsole or jvisualvm to the running Luminus server process to inspect CPU and memory usage.

The lein-sassc plugin provides commands to manage Sass compilation via Leiningen:

• Compile once: Run a single compilation pass.
• Clean: Delete all files generated by lein-sassc.
• Auto-recompile: Watch for changes and recompile automatically.

# Compile files once
lein sassc once

# Delete all generated files
lein sassc clean

# Recompile automatically when changes are detected
lein auto sassc once

Luminus projects are generated using Leiningen. Ensure you have Leiningen 2.0 or above installed on your system to use the Luminus templates.

Note: The template uses placeholders like <<name>> and <<year>> which are replaced during the generation process by the Luminus generator.

lein new luminus:core <<project-name>>

Use the lein new luminus command to create a new Luminus application. By default, this uses the standard profile. You can extend the project's functionality by appending profile hints (e.g., +postgres, +cljs) to the command.

# Create a default Luminus project
lein new luminus <your project name>

# Create a project with specific features (e.g., ClojureScript and PostgreSQL)
lein new luminus myapp +cljs +postgres

To use database features in a Luminus project, you must set up the connection, run migrations, and ensure the database module is loaded by the application lifecycle.

Follow these steps:

1. Create the database: Manually create the target database instance for your application.
2. Update connection URLs: Edit dev-config.edn and test-config.edn to include your specific database name and login credentials.
3. Run migrations: Execute the migration command from the project root to create the required schema/tables.
4. Enable database connection: Ensure the database connection is started by require-ing <<project-ns>>.db.core in another namespace (this allows mount to manage the connection lifecycle).
5. Restart: Restart your application to apply changes.

# Run migrations to create tables
lein run migrate

To start the web server for your generated Luminus application, use the following command in your terminal:

If you are using standard Leiningen:

lein run

If your project is configured to use the boot executable:

boot run

To create an executable Java ARchive (JAR), use lein uberjar. If you initialized your project with the +boot profile, use boot uberjar instead. Once built, you can run the application using the standard java -jar command.

# Build the standalone JAR
lein uberjar

# If using the +boot profile
boot uberjar

# Run the resulting JAR
java -jar target/myapp.jar

To enable MongoDB support in your Luminus project, you must configure the connection parameters and ensure the database is initialized during the application lifecycle.

Follow these steps:

1. Ensure MongoDB is running: Verify that your MongoDB instance is active and reachable.
2. Update configuration files: Set your specific connection parameters (such as host, port, and database name) in both dev-config.edn and test-config.edn.
3. Initialize the connection via mount: To ensure the mount lifecycle manager starts the database connection, you must require your project's core namespace (e.g., your-project-name.core) within another namespace that is part of the application startup.
4. Restart: Restart your application to apply the new configuration.

To use an H2 database with your Luminus project, you must perform the following steps:

1. Create database tables: Run the migration command from the project root to initialize the schema.
2. Initialize database connection: Ensure the database connection is started by require-ing <<project-ns>>.db.core within another namespace in your application. Replace <<project-ns>> with your actual project namespace.
3. Restart: Restart your application to apply the changes.

lein run migrate

To ensure the mount library starts the XTDB node during application startup, you must ensure that <<project-ns>>.db.core is required by another namespace in your project. After making this change, restart the application to initialize the database node.

;; In one of your namespaces, ensure you require the db core:
(require '[<<project-ns>>.db.core :as db-core])

You can enable async ring handling in your application, but be aware that it adds complexity. If an error occurs in an async context, you may see a blank screen without an error message. For async handling to work, the server (e.g., Undertow, Jetty, Servlet) and every middleware in the request chain must support async request handling.

To enable this feature, add :async? true to your configuration maps.

;; Add to your config maps
{:async? true}