Leptos Axum Starter Template

This is a template for use with the Leptos web framework and the cargo-leptos tool using Axum.

Creating your template repo

If you don't have cargo-leptos installed you can install it with

cargo install cargo-leptos --locked

Then run

cargo leptos new --git https://github.com/leptos-rs/start-axum

to generate a new project template.

cd code_submission

to go to your newly created project. Feel free to explore the project structure, but the best place to start with your application code is in src/app.rs. Additionally, Cargo.toml may need updating as new versions of the dependencies are released, especially if things are not working after a cargo update.

Running your project

cargo leptos watch

Copy dev.env to .env, then replace the placeholder with a unique secret before starting the server. The .env file is loaded automatically at startup and is ignored by Git. Startup validates the required settings and stops with a clear error if any are missing or malformed. DEV_SECRET_KEY authorizes server status changes and submission-history access:

Copy-Item dev.env .env

You can also provide DEV_SECRET_KEY through the process environment. Do not commit secrets or expose them in client-side code.

Set PROD=true to make the server start in the live state. Truthy values are 1, true, yes, and on (case-insensitive); an absent or other value starts the server offline.

Code 1 sends an SMS through TextBee when the server is live. Set TEXTBEE_API_KEY, RECIPIENT_SELF, RECIPIENT_1, and RECIPIENT_2 (each a single E.164 number) in .env; TEXTBEE_DEVICE_ID is optional and selects a specific paired device. When live, code 1 sends a notification to self, the congratulations message to recipients 1 and 2, then CHALLENGE_1_FIRST to recipient 1 and CHALLENGE_1_SECOND to recipient 2. The latter two are sent literally as written. When offline, the planned messages are logged instead. TextBee acceptance means a message was queued, not necessarily delivered.

Code 2 uses the former manual code value (Qj4eAn). On successful submission, it sends a notification to RECIPIENT_SELF while the server is live (and logs the notification instead while offline). The result page displays NEXT_STEP_TEXT from src/codes/code2.rs; replace its TODO text with the next step when ready.

The robot submits code 1 with POST /event/buzz and a JSON body containing delay_ms (a non-negative integer) and secret (the value of CODE1_SECRET). The server subtracts the target delay of 6430 ms from delay_ms to calculate the signed buzz delta. Set CODE1_SECRET to a unique random secret of at least 32 bytes in .env. For example, with the server running locally:

curl.exe -X POST http://127.0.0.1:3000/event/buzz -H "Content-Type: application/json" -d '{"delay_ms":6388,"secret":"<your CODE1_SECRET value>"}'

The server calculates 6388 - 6430 = -42 ms for the congratulations message. A valid request returns HTTP 202.

Test code1 with Postman

Create a POST request to http://127.0.0.1:3000/event/buzz, select Body > raw > JSON, and send:

{
  "delay_ms": 6388,
  "secret": "<your CODE1_SECRET value>"
}

Test code1 with Node.js

With the server running and CODE1_SECRET set in your shell, this sends a single test event:

async function main() {
  const delayMs = 6388;
  const secret = process.env.CODE1_SECRET;
  if (!secret) throw new Error("CODE1_SECRET is not set");

  const response = await fetch("http://127.0.0.1:3000/event/buzz", {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({ delay_ms: delayMs, secret }),
  });

  console.log(response.status, await response.text());
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

When the server is live, a successful test event sends the configured TextBee SMS to the configured recipients. When it is offline, it only logs the message.

Installing Additional Tools

By default, cargo-leptos uses nightly Rust, cargo-generate, and sass. If you run into any trouble, you may need to install one or more of these tools.

1. rustup toolchain install nightly --allow-downgrade - make sure you have Rust nightly
2. rustup target add wasm32-unknown-unknown - add the ability to compile Rust to WebAssembly
3. cargo install cargo-generate - install cargo-generate binary (should be installed automatically in future)
4. npm install -g sass - install dart-sass (should be optional in future
5. Run npm install in end2end subdirectory before test

Compiling for Release

cargo leptos build --release

Will generate your server binary in target/release and your site package in target/site

Testing Your Project

cargo leptos end-to-end

cargo leptos end-to-end --release

Cargo-leptos uses Playwright as the end-to-end test tool. Tests are located in end2end/tests directory.

Executing a Server on a Remote Machine Without the Toolchain

After running a cargo leptos build --release the minimum files needed are:

1. The server binary located in target/server/release
2. The site directory and all files within located in target/site

Copy these files to your remote server. The directory structure should be:

code_submission
site/

Set the following environment variables (updating for your project as needed):

export LEPTOS_OUTPUT_NAME="code_submission"
export LEPTOS_SITE_ROOT="site"
export LEPTOS_SITE_PKG_DIR="pkg"
export LEPTOS_SITE_ADDR="127.0.0.1:3000"
export LEPTOS_RELOAD_PORT="3001"

Finally, run the server binary.

Licensing

This template itself is released under the Unlicense. You should replace the LICENSE for your own application with an appropriate license if you plan to release it publicly.