Skip to content

Latest commit

 

History

History
240 lines (196 loc) · 13.6 KB

DEVELOPERS.md

File metadata and controls

240 lines (196 loc) · 13.6 KB

Development Setup

Note: you can open this repository using Gitpod.io for a cloud development environment that is setup with everything you need.

Prerequisites

Make sure you have all the prerequisite tools installed:

  • Node.js v18.17.1 or later.
    • If installing for the first time, it is reccommended that you install it via Node Version Manager. (Mac, Windows)
    • Once NVM is installed, you can install the correct version of Node by running nvm install v18.17.1 in your favorite terminal.
  • Deno.
  • Rancher Desktop
    • Used to make development with extra services (MongoDB, Redis, etc.) easy.
    • It works exactly like docker, except the command is nerdctl.
  • AWS CLI
  • CockroachDB
  • (Windows Only)Visual Studio with C++ tools(Windows Only)
    • Select the "Desktop Development with C++" workflow.

First Time Setup

  1. Clone the repository.
    • git clone https://github.com/casual-simulation/casualos.git
  2. Make sure global dependencies are installed.
    • npm install -g jake node-gyp prisma
    • (Windows Only) Tell NPM to use the global node-gyp. (Older versions of node-gyp cannot detect Visual Studio 2022)
      • Powershell: npm prefix -g | % {npm config set node_gyp "$_\node_modules\node-gyp\bin\node-gyp.js"}
  3. Enable corepack
    • corepack enable
  4. Start CockroachDB
    • Use a separate terminal tab
    • npm run cockroach
    • If you want, you can choose to start CockroachDB when your system starts or use something like Docker to host your CockroachDB instance.
  5. (Optional) Add casualos.localhost to your hosts file.
    • You can use this domain to prevent the service worker from installing.
    • Follow these steps:
      1. Open the hosts file as Sudo/Admin.
        • On Max/Linux it's at /etc/hosts
        • On Windows it's at C:\Windows\System32\drivers\etc\hosts
      2. Add entries to route casualos.localhost to 127.0.0.1: 
        127.0.0.1 casualos.localhost
  6. Start related services:
    • If using nerdctl: npm run nerdctl:dev
    • If using docker: npm run docker:dev
  7. Bootstrap the project.
    • npm run bootstrap
  8. Install commit hooks.
    • npx husky install

Commands

When developing there are a couple of key commands you can run. Most of them are NPM scripts, so they're easy to run.

  • Install existing dependencies
    • npm run boostrap
    • This runs pnpm install --frozen-lockfile which means that the pnpm-lock.yaml file will not be updated. If there are packages that need to be added to the lockfile, you need to run pnpm install manually.
  • Start dev docker services
    • If using nerdctl: npm run nerdctl:dev
    • If using docker: npm run docker:dev
  • Build & Run in Watch Mode
    • npm run watch
    • This will trigger Vite to start in watch mode and run nodemon.
    • When ready, the server will be available at http://localhost:3000.
  • Build in Production Mode
    • npm run build
    • This will trigger Vite in production mode.
    • The output files will be in the dist folders of each project.
  • Run tests In Watch Mode
    • npm run test:watch
  • Run tests
    • npm test
  • Start CockroachDB
    • npm run cockroach
  • Reset your database
    • prisma migrate reset
  • Update your database to match schema (creates a migration if needed)
    • prisma migrate dev

You can find other scripts in the package.json file at the root of the repository.

Deployment Process

Making new releases for CasualOS is pretty simple. All that needs to happen is for the master branch to be updated and pushed to Github. From there a webhook is sent to the CI server which instructs it to make a new build and push it to production.

The version number shown in the app is taken from the most recent git tag. We additionally package the git commit hash just in case master is pushed multiple times without updating the git tag.

Additionally, the CI server will publish the aux-common NPM package whenever the version number in its package.json is updated.

To make a new release, use this process:

  1. Make sure everything you want to release is ready and merged into develop.
  2. Update the CHANGELOG.md file with the next version number, date, and changes that were made since the last version.
  3. Commit the updated CHANGELOG to the develop branch.
  4. Merge the develop branch into the master branch.
  5. Run lerna version.
    • This will look at the changes made and prompt you for the next version number.
    • In most cases all you need to do is select patch.
    • After confirmation lerna will update the package.json version numbers, add a git tag, and push the branch.
  6. You're done.
    • GitHub will send a webhook to the CI server which will make a build and publish everything.

Analyze Build Bundle Size

You can analyze builds to see what is making them large and which dependencies are included.

  1. Go to https://www.bundle-buddy.com/rollup
  2. Run a build with npm run build:server (we only need the server to be built - not all the libraries)
  3. Upload the dependency graph from src/aux-server/aux-web/dist/dependency-graph.json.
  4. Upload the sourcemaps from src/aux-server/aux-web/dist/assets.
  5. Advance to the analysis page by clicking the button at the bottom of the page.

Documentation

The reference documentation is generated automatically from doc comments. Here is a brief list of tags that are used to help generate the documentation:

  • @dochash - This tells the documentation generator which page a type should be placed in. If a type does not have a @dochash tag, then it will only make it into the documentation if it is a child of a type that is included via @dochash. Each unique @dochash ends up as its own page.
  • @doctitle - The title of a page. Only the first @doctitle found for each @dochash will be used.
  • @docsidebar - The title of a page in the sidebar. Only the first @docsidebar found for each @dochash will be used.
  • @docdescription - The SEO description of a page. Only the first @docdescription found for each @dochash will be used.
  • @docname - The visual name of the type/function being documented.
  • @docid - The ID of the type/function being documented. You can use {@link ref} annotations to reference types/functions by their IDs. If omitted, then @docname is used as the ID of a type.
  • @docgroup - An internal group ID for the type. Within a page, types are sorted first by @docgroup, then by @docorder, and finally by @docid.
  • @docorder - An internal order for the type. Within a page, types are sorted first by @docgroup, then by @docorder, and finally by @docid.
  • @docrename - Used to rename a type to reference another type. (e.g. @docrename MyOtherType will cause all references to this type in the documentation to appear as if they are references to MyOtherType)
  • @docsource - Tells the generator to generate an interface with the specified name from the property's type. Useful for properties that utilize type declarations.
  • @docreferenceactions - Tells the generator to find all other types/properties whose IDs match the given regex pattern and include them as extra references for the type.
  • {@link [ref]} - Renders a link to the type with @docid matching [ref].
  • {@tag [tag]} - Renders a link to the given [tag]. Prefix the tag with @ to link to listen tags.

Projects

AUX Server

AUX Docker Pulls AUX ARM32 Docker Pulls

A web application that serves the CasualOS experience. Built on the other projects.

AUX Common

AUX Common NPM

A library that contains common operations needed to modify and understand AUX files.

AUX VM

AUX VM NPM

A set of abstractions and common utilities required to run an AUX on any platform.

Related libraries

AUX Proxy

AUX Docker Pulls

A web service that can facilitate WebSocket tunnels from the external web to a device in an internal network.

Miscellaneous

Tools we use

Here's a list of the tools and packages that we're using to build CasualOS.

If you're using Visual Studio Code, I recommend getting the Jest extension. It makes it real easy to debug unit tests.