uChat

Uchat is a revolutionary full-stack chat app built completely on Rust, while leveraging the capabilities of WASM.

Ethereum wallet connect is live — sign up or log in with MetaMask (or any EIP-6963-compatible wallet) via sign-in-with-Ethereum, no password required. Ethereum Mainnet only; the app prompts a network switch if a different chain is detected.

Demo video is available here

Design

The design/ directory contains some design-related files and assets used throughout the project.

Initial Setup

If you are on Windows, using WSL is highly recommended to manage build dependencies and tooling.

Rust

If you haven't installed Rust yet, you can do so using rustup and then install cargo.

Compiling Rust for the browser requires adding the wasm32 compilation target:

rustup target add wasm32-unknown-unknown

Database

This project uses PostgreSQL for the database. Please follow the official instructions for how to install PostgreSQL on your system. Alternatively, you can use a managed database like Supabase (see the Deployment section below).

Trunk

Trunk is a tool to build and bundle Rust WASM applications. Install it with:

cargo install --locked trunk

# Apple M1/M2/M3 users may also need to install this:
cargo install --locked wasm-bindgen-cli

Diesel CLI

Diesel is a Rust SQL query builder and ORM for working with the database.

Ensure you have PostgreSQL installed locally (or its development libraries) before proceeding.

Install the Diesel CLI with:

cargo install diesel_cli --no-default-features --features postgres

Note: If you receive build or linker errors, make sure you install libpq. This may be packaged separately depending on your operating system and package manager (e.g., libpq-dev on Ubuntu/WSL).

Environment Variables & Database Setup

Create a .env file in the workspace directory containing:

API_DATABASE_URL="postgres://DATABASE_USER:PASSWORD@localhost/uchatfinal"
API_PRIVATE_KEY="API_PRIVATE_KEY_HERE"
API_URL="http://127.0.0.1:8070/"
API_BIND="127.0.0.1:8070"

# Development only
DATABASE_URL="postgres://DATABASE_USER:PASSWORD@localhost/uchatfinal"
TEST_DATABASE_URL="postgres://DATABASE_USER:PASSWORD@localhost/uchatfinal_test"
FRONTEND_URL="http://127.0.0.1:8080"

Substitute the following:

• DATABASE_USER: Role created to access PostgreSQL
• PASSWORD: Your password to login to the database (omit :PASSWORD if not using a password)

After the .env is ready, run this command to create the database:

diesel setup

Generating API_PRIVATE_KEY

The server needs an RSA private key (used to sign session tokens). Generate one with the built-in CLI subcommand:

cargo run --bin api -- gen-key

This writes a base64-encoded key to private_key.base64 in the current directory. Copy its contents into your .env as the value for API_PRIVATE_KEY.

Note: If API_PRIVATE_KEY is not set, the server will generate an ephemeral key on startup and log a warning — existing sessions will not survive a restart. Set the variable for persistent sessions.

npm & Tailwind CSS

This project uses Tailwind CSS for utility classes. You will need Node.js and npm installed to use the npx command for Tailwind.

(Optional) just

just is a handy command runner which simplifies running different development commands. Install it with:

cargo install just

Available Recipes:

Command	Description
just init	Sets up project dependencies and installs npm packages.
just serve-all	Runs both the frontend and backend development servers concurrently.
just serve-pro-all	Runs the frontend and backend in highly optimized release mode.
just test	Runs the test suite using cargo nextest.
just build	Builds the frontend and backend in release mode for production.
just check	Runs cargo check for both frontend (WASM) and backend targets.
just clippy	Runs the cargo clippy linter across the entire codebase.
just fix	Auto-fixes standard linting issues across the codebase.
just db-migrate	Runs pending database migrations and resets the test database.
just db-reset	Wipes and resets the entire PostgreSQL database.
just db-new-migration <NAME>	Generates a new blank database migration.
just doc	Builds and optionally opens the Rust project documentation.
just sweep	Cleans up old cargo build artifacts to free up disk space.

Commands

Project Initialization

This will check for the dependencies listed above and attempt to install the required Rust dependencies. It will provide installation links for dependencies that require manual installation.

cargo run -p project-init

Documentation

To build the documentation:

cargo doc -F docbuild

(Note: Enabling the docbuild feature is a temporary workaround for a minor bug in a transitive dependency.)

Development Server

To run a development server for the frontend and open a new browser window:

trunk serve --open

To run the backend server:

cargo run -p uchat_server

Check / Clippy

Check the frontend and backend targets:

cargo check -p frontend --target wasm32-unknown-unknown
cargo check --workspace --exclude frontend

Run clippy for the frontend and backend targets:

cargo clippy -p frontend --target wasm32-unknown-unknown
cargo clippy --workspace --exclude frontend

Testing

This project uses cargo-nextest as a faster, more robust test runner.

1. Install nextest (if you haven't already):

   cargo install cargo-nextest --locked

2. Run the test suite: The test suite includes full-stack integration tests (such as simulating a user logging in and creating a post) as well as data validation unit tests. You can run all tests across the workspace with:

   cargo nextest run

   (Note: The TEST_DATABASE_URL environment variable in your .env must be configured properly to run the integration tests).

Build for Production

To build the project for distribution:

trunk --config Trunk-release.toml build
cargo build --release --workspace --exclude frontend

To run the production build locally:

Frontend:

trunk serve --release --config Trunk-release.toml

Backend: Navigate to target/release/ and run the executable:

cd target/release/
./api

Migrations

To create new database migrations, run:

diesel migration generate MIGRATION_NAME

This creates a new folder in data/migrations/timestamp_MIGRATION_NAME/. Add your SQL for applying the migration to up.sql and the SQL for reverting it to down.sql.

Apply the migration with:

diesel migration run

To verify your down.sql works, run this command to revert and then reapply the migration:

diesel migration redo

After creating a new migration, you may want to delete the testing database:

psql -d postgres -c 'DROP DATABASE IF EXISTS uchat_test;'

Deployment

This project's architecture is fully decoupled, making it perfectly suited for modern "best-of-breed" free-tier hosting platforms.

1. Deploying the Database to Neon.tech

We recommend using Neon.tech for a Serverless PostgreSQL database.

1. Create a new free tier project on Neon.
2. Retrieve your Connection String (it will look like postgres://username:password@.../neondb).
3. Run your migrations against this database locally:

   DATABASE_URL="<your-neon-connection-string>" diesel migration run

(Alternatively, you can also use Supabase following a similar process).

2. Deploying the Backend to Render

Render.com provides native Rust build environments without needing a Dockerfile.

1. Create a new Web Service on Render and connect your GitHub repository.
2. Configure the build settings:
   • Language/Environment: Rust
   • Build Command: cargo build --release -p uchat_server
   • Start Command: ./target/release/api
3. Under Environment Variables, add the following:
   • API_DATABASE_URL: (Your Neon Connection String)
   • API_BIND: 0.0.0.0:10000
   • PORT: 10000
   • FRONTEND_URL: https://your-frontend-app.netlify.app (Must match your Netlify domain exactly, without a trailing slash)
4. Click Deploy.

3. Deploying the Frontend to Netlify

Netlify will automatically build the Trunk WebAssembly frontend and serve it over a global CDN.

1. Connect your repository to Netlify. Netlify will automatically detect the netlify.toml file and its build configuration.
2. Go to Site Settings > Environment Variables and add:
   • API_URL: https://your-backend-app.onrender.com/ (Make sure to include the trailing slash if required by your API client)
3. Trigger a manual deploy in the Deploys tab to ensure the environment variable is injected during the build process.

(Note: The netlify.toml file is configured to create an empty .env file during the build process to satisfy the load_dotenv!() macro requirements without needing to commit your secrets).