akkounts/README.md

[![Build Status](https://gitea.kosmos.org/kosmos/akkounts/actions/workflows/ci.yml/badge.svg)](https://gitea.kosmos.org/kosmos/akkounts/actions)

# Akkounts

This app allows Kosmos/LDAP users to manage their accounts, including
credentials, invites, donations, etc..

## Development

### Quick Start

The easiest way to get a working development setup is using Docker Compose like
so:

1. Make sure [Docker Compose is installed][1] and Docker is running (included in
   Docker Desktop)
2. Run `docker compose up --build` and wait until all services have started
   (389ds might take an extra minute to be ready). This will take a while when
   running for the first time, so you might want to do something else in the
   meantime.

On the first start, the `ldap-init` service creates the 389ds back-end, and the
`web` container then seeds the LDAP directory and the databases automatically.
On every start, `web` also applies any pending database migrations.

After these steps, you should have a working Rails app with a handful of test
users running on [http://localhost:3000](http://localhost:3000).
Log in with username "admin" and password "admin is admin". All users listed on
[http://localhost:3000/admin/users](http://localhost:3000/admin/users)
have the password "user is user".

### Rails app

_Note: when using Docker Compose, prefix the following commands with `docker-compose
run web`._

Installing dependencies:

    bundle install
    bun install

Migrating the local database (after schema changes):

    bundle exec rails db:migrate

Running the dev server, and auto-building CSS files on change _(automatic with Docker Compose)_:

    bin/dev

Running the background workers (requires Redis) _(automatic with Docker Compose)_:

    bundle exec sidekiq -C config/sidekiq.yml

Running the test suite:

    bundle exec rspec

Running the test suite with Docker Compose requires overriding the Rails
environment:

    docker-compose exec -e "RAILS_ENV=test" web rspec

### Docker Compose

Services/containers are configured in `docker-compose.yml`.

You can run services selectively, for example if you want to run the Rails app
and test suite on the host machine. Just add the service names of the
containers you want to run to the `up` command, like so:

    docker-compose up ldap redis

#### LDAP server

On first start, the `ldap-init` service creates the dirsrv back-end
automatically, and the `web` container then seeds it with development entries.
To do either step manually (for example, after changing the setup), run:

    docker compose exec ldap dsconf localhost backend create --suffix="dc=kosmos,dc=org" --be-name="dev"
    docker compose run --rm web bin/rails ldap:setup

The setup task will first delete any existing entries in the directory tree
("dc=kosmos,dc=org"), and then create our development entries.

Note that all 389ds data is stored in the `389ds-data` volume. So if you want
to start over with a fresh installation, delete both that volume as well as the
container.

To reset the development environment completely, remove all volumes plus the
generated database files and the first-run marker, then start over:

    docker compose down -v
    rm -f db/*.sqlite3 tmp/.setup-complete
    docker compose up --build

#### Garage / remoteStorage

remoteStorage accounts use the `garage` S3-compatible object store. On first
start, Garage automatically configures a single-node cluster and creates the
`remotestorage` bucket together with a `dev-key1` access key (secret
`1234567890123456`), so no manual setup is required.

If you want to run remoteStorage accounts locally, the `garage` container is
started by default when using Docker Compose. To run just the remoteStorage
stack:

* `docker compose up web redis garage liquor-cabinet`

The S3 API is available at http://localhost:3900 (region `garage`). If you want
to start over with a fresh storage, delete the `garage-data` volume as well as
the container.

#### Accessing remoteStorage from another machine

remoteStorage clients force HTTPS for any host except `localhost`, and browsers
block plain-HTTP requests to a LAN IP as mixed content. To connect to the dev
remoteStorage from a browser on another machine (including production apps such
as Inspektor), forward the ports over SSH and connect as `localhost`:

    ssh -N -L 3000:localhost:3000 -L 4567:localhost:4567 <user>@<dev-host>

Then use `<user>@localhost:3000` as the remoteStorage address in the client.
WeFinger discovery and storage requests are served through the forwarded ports,
so no TLS setup is needed.

### Adding npm modules to use with Stimulus controllers

The following command downloads the specified npm module to `vendor/javascript`
and adds an entry for it to `config/importmap.rb`.

    bin/importmap pin bech32 --download

### Solargraph

[Solargraph](https://solargraph.org/) is a Ruby language server, which you may
use with your editor to add features like auto-completion and syntax
validation. You can add inline documentation for bundled gems with this
command:

    bundle exec yard gems

## Documentation

### Rails

* [Ruby on Rails](https://guides.rubyonrails.org/)
* [Pagination](https://ddnexus.github.io/pagy/)

### Front-end

* [Icons](https://feathericons.com)
* [Tailwind CSS](https://tailwindcss.com/)
* [Sass](https://sass-lang.com/documentation)
* [Stimulus](https://stimulus.hotwired.dev/handbook/)
* [Tailwind Stimulus Components](https://github.com/excid3/tailwindcss-stimulus-components)

### Testing

* [RSpec](https://rspec.info/documentation/)
* [Capybara](https://rubydoc.info/github/teamcapybara/capybara/master)

### LDAP / Auth

* [devise_ldap_authenticatable](https://github.com/cschiewek/devise_ldap_authenticatable)
* [net/ldap](https://www.rubydoc.info/gems/net-ldap/Net/LDAP)

### Asynchronous jobs/workers

* [Sidekiq](https://github.com/mperham/sidekiq/wiki/)
* [ActiveJob](https://github.com/mperham/sidekiq/wiki/Active-Job)

### Feature Flags

* [Flipper](https://www.flippercloud.io/docs/get-started/self-hosted)

## License

[GNU Affero General Public License v3.0](https://choosealicense.com/licenses/agpl-3.0/)

[1]: https://docs.docker.com/compose/install/