161 lines
5.1 KiB
Markdown
161 lines
5.1 KiB
Markdown
[](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 --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.
|
|
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
|
|
|
|
_Note: when using Docker Compose, prefix the following commands with `docker-compose
|
|
run web`._
|
|
|
|
Installing dependencies:
|
|
|
|
bundle install
|
|
yarn 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
|
|
|
|
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 the `389ds-data` volume. So if you want
|
|
to start over with a fresh installation, delete both that volume as well as the
|
|
container.
|
|
|
|
#### Minio / remoteStorage
|
|
|
|
If you want to run remoteStorage accounts locally, you will have to create the
|
|
respective bucket first. With the `minio` container running (run by default
|
|
when using Docker Compose), follow these steps:
|
|
|
|
* `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
|
|
|
|
* [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/
|