kosolabs/koso

Development Environment (MacOS)

First Time Setup

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Install PostgreSQL.
```
brew install postgresql@16
```
Start PostgreSQL.
```
brew services start postgresql@16
```
Install Rust.
```
brew install rustup
rustup-init
```
The backend uses SQLx to interact with PostgreSQL. Install the SQLx in order to run migrations and perform other administrative operations.
```
cargo install sqlx-cli --no-default-features --features rustls,postgres
```
Configure SQLx with the DATABASE_URL.
```
export DATABASE_URL=postgresql://localhost/koso
```
Also, add the environment variable to the appropriate profile file (~/.profile, ~/.bash_profile, ~/.bashrc, ~/.zshrc, ~/.zshenv) so you don't have to run it every time.
Create the database and run the DB migrations.

In the backend folder, run:
```
sqlx database create
sqlx migrate run
```
Install Node.js.
```
brew install node
```
Install the frontend dependencies.

In the frontend folder, run:
```
npm install
```

Start Backend and Frontend

Start the backend server.

In the backend folder, run:
```
cargo run
```
Start the frontend server.

In the frontend folder, run:
```
npm run dev
```
Navigate to http://localhost:5173/

VS Code

The Koso Workspace is configured for development in VS Code.

The following plugins are recommended:

DB Migrations

Add a migration:

sqlx migrate add some-meaningful-name

Run migrations

sqlx migrate run

Backend Interactions

Once a server has been started, you can interact with it at http://localhost:3000. There are example requests in koso.http which you can run with REST Client.

Backend Auto-reload

Tired of manually restarting your server after editing the code? Use systemfd and cargo-watch to automatically recompile and restart the server whenever the source code changes. It uses listenfd to be able to migrate connections from an old version of the app to a newly-compiled version.

One time setup:

cargo install cargo-watch systemfd

Running:

systemfd --no-pid -s http::3000 -- cargo watch -x run

Running a Built Frontend with the Backend

This setup is similar to how the app will run in production. A single server serves the API, WebSocket, and static frontend files.

In the frontend folder, run:
```
npm run build
```

In the backend folder, run the server:

systemfd --no-pid -s http::3000 -- cargo watch -x run

This will create a frontend/build folder. The backend/static folder is symlinked to that folder and will serve the compiled frontend directly from the backend.

kosolabs / koso