linkpulse/README.md

linkpulse

A project for monitoring websites, built with FastAPI and React.

Structure

A description of the project's folder structure.

• /backend A backend server using FastAPI, managed with Poetry.
  • /backend/linkpulse A python module containing the FastAPI application, database models, migration scripts, and more.
  • /backend/migrations Migration scripts for peewee; most of this is generated automatically.
• /frontend A frontend server using React, managed with pnpm, built with 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 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

I recommend asdf or nvm for managing this (although asdf is superior in my opinion, and it's tool/language agnostic). Alternatives are available though.

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 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.

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 <version> or asdf install nodejs latest:<version>. 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

1. Install pyenv or pyenv-win

   • Install Python 3.12 (pyenv install 3.12)

2. Install poetry

   • Requires pipx, see here. 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

   • Fastest installation is via shell: bash <(curl -fsSL cli.new)
     • Alternatives found here.
   • 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 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 for a list of all available environment variables.
   • For the frontend, the defaults are already sufficient.

Warning

The run.sh scripts provide default environment variables internally; if you want to run the commands manually, you'll need to provide them to .env files or the command line.