05158eb10c
A handful of things have changed since last year, so the README should reflect that. Signed-off-by: André Jaenisch <andre.jaenisch@posteo.de>
149 lines
4.8 KiB
Markdown
149 lines
4.8 KiB
Markdown
<!--
|
|
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).
|