Anvil/README.md

<!--
SPDX-FileCopyrightText: 2023 Pere Lev

SPDX-License-Identifier: AGPL-3.0-or-later
-->

# Anvil

/!\ work in progress!

[Kanban](https://tree.taiga.io/project/perelev-anvil) |
[Chat](https://matrix.to/#/#general-forgefed:matrix.batsense.net)

Anvil is a web client app for interacting with federated forges. It's meant to
allow you to:

- Create an account of a federated forge
- Browse software projects
- Create and manage your software projects
- Create and manage teams and organizations
- Participate and interact with software projects: Repo, issues, PRs, CI, etc.
  etc.

It's meant to be deployed in 3 ways:

1. [Tauri](https://tauri.app) app, packaged with Flatpak, that you can install
   on your desktop
2. Independent fully-client-side hosted app you can access using a web browser
   and connect to any forge (we will probably host one on Anvil's website for
   convenient outreach, but anyone can host on their server)
3. Hosted app served by federated forge servers as their default UI, supporting
   both multi-page mode with pre-rendered pages and regular single-page mode

Status (May 2024): Implementation is in very early initial stages.

You can build Anvil with Tauri to a native app.
Since Progressive Enhancement philosophy is followed the security model of the
web browsers make it hard to have a completely client-side application. We will
look into this in a future point in time again.

Tech stack:

- SvelteKit
- TypeScript
- Tailwind
- Skeleton.dev
- Tauri

Soon also:

- ActivityPub
- ForgeFed

## Developing

Install NodeJS. Recommended method: [FNM](https://github.com/Schniz/fnm).

Install dependencies:

```bash
npm install
```

Launch development server:

```bash
npm run dev

# or start the server and open the app in a new browser tab
npm run dev -- --open
```

Quick overview of the structure of the codebase:

- `.reuse` - This folder holds configuration for [REUSE](https://reuse.software/)
- `.vscode` - This folder holds configuration for Visual Studio Code
- `LICENSES` - Used in conjunction with REUSE
- `src` - The source code of the web application (server and client)
- `src-tauri` - Glue code for Tauri to turn it into a native application
- `static` - Static assets (FavIcon)
- `tests` - Mainly Svelte component tests for the client
- `.eslintignore` and `.eslintrc.cjs` - ESLint ignore and configuration files
- `.gitignore` - Files and folders not to be subjected to version control
- `.node-version` - Minimum of supported NodeJS version
- `*.license` - Files to be used in conjunction with REUSE
- `.npmrc` - NPM configuration file
- `.prettierignore` and `.prettierrc` - Prettier ignore and configuration files
- `COPYING` - License of this project under AGPL
- `package-lock.json` and `package.json` - NPM package lockfile for dependencies
  and meta information about this project
- `playwright.config.ts` - Playwright End-to-End test configuration
- `postcss.config.cjs` - PostCSS postprocessor configuration file
- `README.md` - This document
- `svelte.config.js` - Svelte configuration file
- `tailwind.config.js` - Tailwind CSS configuration file
- `tsconfig.json` - TypeScript configuration file
- `vite.config.ts` - Vite bundler configuration file
- `vitest.config.ts` - Vitest test runner configuration file

## Building

We have installed the [Node servers adapters](https://kit.svelte.dev/docs/adapter-node) for
the target environment. There is no cloud-native build target at this point.

To create a production version of the app:

```bash
npm run build
```

To preview the production build:

```bash
npm run preview
```

## Deployment

There is a [demo instance](https://anvil.demo.jaenis.ch/) available.
Log in with credentials from [fig](https://fig.fr33domlover.site/) to test it
with real data or use any other credentials you like (to see test data).

If you want to run an instance yourself, adapt the
[SystemD service file](https://kit.svelte.dev/docs/adapter-node#socket-activation)
to your setup. For example, running behind a reverse proxy on port 8080
on https://anvil.domain.example/ would look similiar to this:

```
[Service]
Environment=NODE_ENV=production IDLE_TIMEOUT=60 ORIGIN=https://anvil.domain.example PORT=8080
ExecStart=/usr/bin/node /opt/anvil
```

This assumes the repository was cheked out and the
[build artifacts](https://kit.svelte.dev/docs/adapter-node#deploying) reside in
`/opt/anvil`. See
[SvelteKit documentation on environment variables](https://kit.svelte.dev/docs/adapter-node#environment-variables-origin-protocolheader-hostheader-and-port-header)
to learn more.

## Storybook

Find a [component library online](https://anvil.codeberg.page/Anvil/).
This is loosely kept in sync with the main branch because there is a dependency
mismatch between Storybook dependencies and what we want to use.

## Software freedoms (a.k.a license)

GNU AGPL v3 or later. For the legal detail, see [`COPYING`](COPYING).