NPO-Accounting/houdini
6
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Improve readme formatting

Browse source
This commit is contained in:
Eric 2020-07-31 11:36:57 -05:00 committed by Eric Schultz
parent ae0e3e0da0
commit 79fe9042ac
1 changed files with 52 additions and 40 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

92
README.md
View file

@ -1,14 +1,14 @@
[![](https://img.shields.io/badge/zulip-join_chat-brightgreen.svg)](https://houdini.zulipchat.com) [![](https://img.shields.io/badge/zulip-join_chat-brightgreen.svg)](https://houdini.zulipchat.com)
![Houdini build](https://github.com/houdiniproject/houdini/workflows/Houdini%20build/badge.svg) ![Houdini build](https://github.com/houdiniproject/houdini/workflows/Houdini%20build/badge.svg)
* NOTE: This is the latest version (pre-2.0) of Houdini and > *Note*: This is the latest version (pre-2.0) of Houdini and
is currently in HEAVY development. You may want > is currently in HEAVY development. You may want
to use > to use
[v1](https://github.com/houdiniproject/houdini/tree/1-0-stable) > [v1](https://github.com/houdiniproject/houdini/tree/1-0-stable)
instead. > instead.
The Houdini Project is free and open source fundraising infrastructure. It includes... The Houdini Project is free and open source fundraising infrastructure. It includes...
- Crowdfunding campaigns - Crowdfunding campaigns
- Donate widget page and generator - Donate widget page and generator
- Fundraising events - Fundraising events
@ -27,7 +27,9 @@ comfort and speed.
All new backend code and React components well tested. All new backend code and React components well tested.
## Prerequisites ## Prerequisites
Houdini is designed and tested to run with the following: Houdini is designed and tested to run with the following:
* Ruby 2.6 * Ruby 2.6
* Node 14 * Node 14
* Yarn * Yarn
@ -35,22 +37,28 @@ Houdini is designed and tested to run with the following:
* Ubuntu 18.04, 20.04 or equivalent * Ubuntu 18.04, 20.04 or equivalent
## Get involved ## Get involved
Houdini's success depends on you! Houdini's success depends on you!
### Join our Zulip chat ### Join our Zulip chat
https://houdini.zulipchat.com https://houdini.zulipchat.com
### Help with translations ### Help with translations
Visit the Internationalization channel on Houdini Zulip and discuss Visit the Internationalization channel on Houdini Zulip and discuss
## Dev Setup ## Dev Setup
#### Tips for specific circumstances #### Tips for specific circumstances
* Docker: Docker was previously used for development of Houdini. * Docker: Docker was previously used for development of Houdini.
See [docker.md](docs/docker.md) for more info. See [docker.md](docs/docker.md) for more info.
* Mac: Mac dev setup may require some unique configuration. * Mac: Mac dev setup may require some unique configuration.
See [mac_getting_started.md](docs/mac_getting_started.md) for more info. See [mac_getting_started.md](docs/mac_getting_started.md) for more info.
### Installation prep ### Installation prep
Houdini requires a few pieces of software be installed, as well as some optional pieces Houdini requires a few pieces of software be installed, as well as some optional pieces
which make development much easier. which make development much easier.
@ -58,12 +66,13 @@ These include:
* PostgreSQL 12 (10 probably works) * PostgreSQL 12 (10 probably works)
* NodeJS 14 (we require 14 because we want the full internationalization built-in) * NodeJS 14 (we require 14 because we want the full internationalization built-in)
* Ruby 2.6.6 (NOTE: the default of Ruby 2.7.1 in Debian should * Ruby 2.6.6 (NOTE: the default of Ruby 2.7.1 in Debian should
function but you will receive a ton of deprecation function but you will receive a ton of deprecation
warnings from Ruby) warnings from Ruby)
There a few optional tools which make working on Houdini There a few optional tools which make working on Houdini
easiter easier
* Ruby Version Manager (RVM) - RVM makes it simple to switch * Ruby Version Manager (RVM) - RVM makes it simple to switch
between versions of Ruby for different projects. Additionally, you can between versions of Ruby for different projects. Additionally, you can
use different "gemsets" per version so you can separate the use different "gemsets" per version so you can separate the
@ -91,21 +100,21 @@ apt install git postgresql-12 libpq-dev libjemalloc-dev libvips42 yarn -yy
You'll run the next commands as your normal user. You'll run the next commands as your normal user.
NOTE: in the case of a production instance, this might be > *Note*: in the case of a production instance, this might be
your web server's user. > your web server's user.
NOTE 2: We use [RVM](https://rvm.io) to have more control over the exact version of Ruby. For development, it's also way easier because you can > *Note*: We use [RVM](https://rvm.io) to have more control over the exact version of Ruby. For development, it's also way easier because you can
use a consistent version of Ruby (and different sets of installed gems) for different projects. You could also use rbenv > use a consistent version of Ruby (and different sets of installed gems) for different projects. You could also use rbenv
or simply build ruby from source. > or simply build ruby from source.
NOTE 3: We don't recommend using Ruby 2.7, the current Ubuntu default at this time. Ruby 2.7 will function but spits out tons > *Note*: We don't recommend using Ruby 2.7, the current Ubuntu default at this time. Ruby 2.7 will function but spits out tons
of deprecation warnings when using Rails applications. > of deprecation warnings when using Rails applications.
NOTE 4: We recommend building Ruby with jemalloc support as we > *Note*: We recommend building Ruby with jemalloc support as we
do in these instructions. In practice, it manages memory far > do in these instructions. In practice, it manages memory far
more efficiently in Rails-based projects. > more efficiently in Rails-based projects.
TIP: To get out of the root shell, run `exit` > *Tip*: To get out of the root shell, run `exit`
```bash ```bash
# add rvm keys # add rvm keys
@ -120,10 +129,10 @@ rvm install 2.6.6 --disable-binary --with-jemalloc
Run the following command as the `postgres` user and then enter your houdini_user Run the following command as the `postgres` user and then enter your houdini_user
password at the prompt. password at the prompt.
NOTE: For development, Houdini expects the password to be 'password'. This would be terrible > *Note*: For development, Houdini expects the password to be 'password'. This would be terrible
for production but for development, it's likely not a huge issue. for production but for development, it's likely not a huge issue.
TIP: To run this, add `sudo -u postgres ` to the beginning of the following command. > *Tip*: To run this, add `sudo -u postgres ` to the beginning of the following command.
`createuser houdini_user -s -d -P` `createuser houdini_user -s -d -P`
@ -140,14 +149,14 @@ Let's run the Houdini project setup and we'll be ready to go!
bin/setup bin/setup
``` ```
NOTE: The .env file holds your environment variables for development; on production you might > *Note*: The .env file holds your environment variables for development; on production you might
have these set somewhere else other than this file. > have these set somewhere else other than this file.
TIP: On Heroku, the environment variables are set in your Dashboard. > *Tip*: On Heroku, the environment variables are set in your Dashboard.
Also, you should set the STRIPE_API_KEY and STRIPE_API_PUBLIC Also, you should set the STRIPE_API_KEY and STRIPE_API_PUBLIC
environment variables which you'd get from the Stripe environment variables which you'd get from the Stripe
dashboard. On your development environment, dashboard. On your development environment,
make sure to use test keys. If you don't, you're make sure to use test keys. If you don't, you're
going to be charged real money! going to be charged real money!
@ -158,26 +167,28 @@ To verify everying is set up correctly, you can try running through the test cas
```bash ```bash
./bin/rails spec ./bin/rails spec
``` ```
You should expect to see the output of the test execution, You should expect to see the output of the test execution,
including messages about pending test cases, and including messages about pending test cases, and
eventually get the output to the effect of below: eventually get the output to the effect of below:
``` ```text
Finished in 6 minutes 25 seconds (files took 10.35 seconds to load) Finished in 6 minutes 25 seconds (files took 10.35 seconds to load)
2433 examples, 0 failures, 42 pending 2433 examples, 0 failures, 42 pending
Coverage report generated for RSpec to .../houdini/coverage. 10552 / 12716 LOC (82.98%) covered. Coverage report generated for RSpec to .../houdini/coverage. 10552 / 12716 LOC (82.98%) covered.
``` ```
The important thing to look for is that the number of The important thing to look for is that the number of
failures is zero. failures is zero.
#### Startup #### Startup
`bin/rails server` `bin/rails server`
You can connect to your server at http://localhost:5000 You can connect to your server at http://localhost:5000
##### Super admin ##### Super admin
There is a way to set your user as a super_admin. This role lets you access any of the nonprofits There is a way to set your user as a super_admin. This role lets you access any of the nonprofits
on your Houdini instance. Additionally, it gives you access to the super admin control panel to search all supporters and on your Houdini instance. Additionally, it gives you access to the super admin control panel to search all supporters and
nonprofits, which is located at `/admin` url. nonprofits, which is located at `/admin` url.
@ -187,34 +198,35 @@ To create the super user, go to the rails console by calling:
`bin/rails console` `bin/rails console`
In the console, run the following: In the console, run the following:
``` ```ruby
admin=User.find(1) #or the id of the user you want to add the role admin=User.find(1) #or the id of the user you want to add the role
role=Role.create(user:admin,name: "super_admin") role=Role.create(user:admin,name: "super_admin")
``` ```
## Known Issues ## Known Issues
For a list of [how to solve known issues](docs/KNOWN_ISSUES.MD) For a list of [how to solve known issues](docs/KNOWN_ISSUES.MD)
## Run in production ## Run in production
You will likely want to make a few changes in your configuration of Houdini before running in production as you You will likely want to make a few changes in your configuration of Houdini before running in production as you
would for any Rails project. These include: would for any Rails project. These include:
* Using a [different ActiveJob backend](https://guides.rubyonrails.org/active_job_basics.html). NOTE: The Sneakers for RabbitMQ doesn't * Using a [different ActiveJob backend](https://guides.rubyonrails.org/active_job_basics.html). NOTE: The Sneakers for RabbitMQ doesn't
work properly. There are work properly. There are
[forks of Sneakers](https://github.com/veeqo/advanced-sneakers-activejob) [forks of Sneakers](https://github.com/veeqo/advanced-sneakers-activejob)
which might work but they haven't been tested. **If you do test which might work but they haven't been tested. **If you do test
them please let us know!** them please let us know!**
* Use a [proper cache store](https://guides.rubyonrails.org/caching_with_rails.html#cache-stores). The development uses * Use a [proper cache store](https://guides.rubyonrails.org/caching_with_rails.html#cache-stores). The development uses
`memory_store` which isn't shared between processes or server `memory_store` which isn't shared between processes or server
and clears every time your server software restarts. Memcached and clears every time your server software restarts. Memcached
or Redis are good choices here. or Redis are good choices here.
### Providing the complete corresponding source code ### Providing the complete corresponding source code
**Note: This is not legal advice and provides a suggestion which may be compliant. You should talk with your legal counsel if you have > **Note: This is not legal advice and provides a suggestion which may be compliant. You should talk with your legal counsel if you have
questions or concerns with how to comply with the various licenses of Houdini** > questions or concerns with how to comply with the various licenses of Houdini.**
Providing the complete, corresponding source code (CCS) of your project is a requirement of some of the licenses used by Houdini. There are two methods for doing so right now: Providing the complete, corresponding source code (CCS) of your project is a requirement of some of the licenses used by Houdini. There are two methods for doing so right now:
@ -226,4 +238,4 @@ For this to work though, the following characteristics must be true:
* Your have to have committed any changes you made to the project in `HEAD` in your git repository * Your have to have committed any changes you made to the project in `HEAD` in your git repository
* The `.git` folder for your repository must be a direct subfolder of your `$RAILS_ROOT` * The `.git` folder for your repository must be a direct subfolder of your `$RAILS_ROOT`
* Your web server must be able to run `git archive`. * Your web server must be able to run `git archive`