akkounts/README.md

[![Build Status](https://drone.kosmos.org/api/badges/kosmos/akkounts/status.svg)](https://drone.kosmos.org/kosmos/akkounts)

# 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)
3. Run `docker compose up` and wait until 389ds announces its successful start
   in the log output
4. `docker-compose exec ldap dsconf localhost backend create --suffix="dc=kosmos,dc=org" --be-name="dev"`
5. `docker compose run web rails ldap:setup`
6. `docker compose run web rails db:setup`

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

Installing dependencies:

    bundle install
    yarn install

Setting up local database (SQLite):

    bundle exec rails db:create
    bundle exec rails db:migrate

Running the dev server and auto-building CSS files on change:

    bin/dev

Running the background workers (requires Redis):

    bundle exec sidekiq -C config/sidekiq.yml

Running all specs:

    bundle exec rspec

### Docker (Compose)

There is a working Docker Compose config file, which define a number of services including
an app server for Rails as well as a local 389ds (LDAP) server.

For Rails developers, you probably just want to start the LDAP server: `docker-compose up ldap`, 
listening on port 389 on your machine. 

You can pick and choose your services adding them by name (listed in `docker-compose.yml`) at 
the end of the docker compose command. eg. `docker compose up ldap redis`

#### LDAP server

After creating the Docker container for the first time (or after deleting it),
you need to run the following command once, in order to create the dirsrv
back-end:

    docker-compose exec ldap dsconf localhost backend create --suffix="dc=kosmos,dc=org" --be-name="dev"

Now you can seed the back-end with data using this Rails task:

    bundle exec 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 `tmp/389ds`. So if you want to start over
with a fresh installation, delete both that directory as well as the container.

#### Minio / RS

If you want to run remoteStorage accounts locally, you will have to create the
respective bucket first:

* `docker compose up web redis minio liquor-cabinet`
* Head to http://localhost:9001 and log in with user `minioadmin`, password
  `minioadmin`
* Create a new bucket called `remotestorage` (or whatever you
  change the `S3_BUCKET` config to)
* Create a new key with ID "dev-key" and secret "123456789" (or whatever you
  change `S3_ACCESS_KEY` and `S3_SECRET_KEY` to). Leave the policy field empty,
  as it will automatically allow access to the bucket you created.

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

* [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/