diff --git a/README.md b/README.md index 62cc4a2..8212f9c 100644 --- a/README.md +++ b/README.md @@ -1,25 +1,49 @@ # linkpulse -This is an empty project right now. It merely holds a simplistic FastAPI server to showcase Railway. +A project for monitoring websites, built with FastAPI and React. -- Windows WSL is recommended for development. See [here][wsl] for setup instructions. +## Structure -## Project Structure +A description of the project's folder structure. - `/backend` A backend server using [FastAPI][fastapi], managed with [Poetry][poetry]. -- `/frontend` A frontend server using [React][react], managed with [pnpm][pnpm]. + - `/backend/linkpulse` A python module containing the FastAPI application, database models, migration scripts, and more. + - `/backend/migrations` Migration scripts for [`peewee`][peewee]; most of this is generated automatically. +- `/frontend` A frontend server using [React][react], managed with [pnpm][pnpm], built with [Vite][vite]. + - `/frontend/Caddyfile` A Caddy configuration file used for proxying API requests to the backend server via Private Networking (Railway). + - `/frontend/nixpacks.toml` Configures the frontend build process for Nixpacks, enabling the use of Caddy for deployment. ## Setup +Windows WSL is **strongly recommended** for development. See [here][wsl] for setup instructions. + +The following instructions were written for Ubuntu 22.04 LTS, the primary (default) target for WSL. + ### Frontend 1. Install Node.js 22.x - -3. Install `pnpm` with `npm install -g pnpm` + +I recommend [`asdf`][asdf] or [`nvm`][nvm] for managing this (although `asdf` is superior in my opinion, and it's tool/language agnostic). [Alternatives are available though](https://nodejs.org/en/download/package-manager). + +Assuming you're using Bash/Zsh & Git, you'll need to add this to your bashrc file: `. "$HOME/.asdf/asdf.sh"`. Shell completions are recommended, but optional. Refer to documentation [here][asdf-install] for further detail. + +Once added, restart your terminal and `cd` into the project root. + +``` +asdf plugin add nodejs +asdf install +``` + +This installs the version of Node.js specified in [`.tool-versions`](.tool-versions). + +>[!NOTE] If you use Node.js for other projects, you may want to install the version you need & set it as the global version via `asdf global nodejs ` or `asdf install nodejs latest:`. If you don't care, `asdf install latest nodejs` also works. + +2. Install `pnpm` with `npm install -g pnpm` +3. `cd frontend` 4. Install frontend dependencies with `pnpm install` 5. Start the frontend server with `./run.sh` - + ### Backend @@ -29,21 +53,32 @@ This is an empty project right now. It merely holds a simplistic FastAPI server 2. Install `poetry` - - Requires `pipx`, see [here][pipx] + - Requires `pipx`, see [here][pipx]. You will NOT have this by default. This is NOT `pip`, do not install either with `pip`. - Install with `pipx install poetry` 3. Install backend dependencies with `poetry install`. 4. Start the backend server with `./run.sh` - +5. (*optional*) Install the [Railway CLI][railway] + - Fastest installation is via shell: `bash <(curl -fsSL cli.new)` + - Alternatives found [here][railway]. + - This will let us skip creating a local `.env` file, as well as keeping your database URL synchronized. + - You will have to run `railway login` upon install as well as `railway link` in the backend directory. ## Usage -- A fully editable (frontend and backend), automatically reloading project is possible, but it requires two terminals. - - Each terminal must start in the respective directory (`/backend` and `/frontend`). - - `./run.sh` will start the development server in the respective directory. - - The first argument is optional, but can be used in the frontend to compile & serve the backend. - +A full stack (*frontend* and *backend*), automatically reloading project is possible, but it requires two terminals. + +1. Open a terminal in each respective directory (`/backend` and `/frontend`). +2. Execute `./run.sh` to start the development server for each. + - For the backend, you'll either need to have the `railway` CLI installed or a `.env` file with the database URL. + - See [`.env.example`](backend/.env.example) for a list of all available environment variables. +[peewee]: https://docs.peewee-orm.com/en/latest/ +[railway]: https://docs.railway.app/guides/cli +[vite]: https://vite.dev/ +[asdf]: https://asdf-vm.com/ +[asdf-install]: https://asdf-vm.com/guide/getting-started.html#_3-install-asdf +[nvm]: https://github.com/nvm-sh/nvm [fastapi]: https://fastapi.tiangolo.com/ [poetry]: https://python-poetry.org/ [react]: https://react.dev/