Browse Source

doc: License, contributing guide, reworked Readme

Refs: #39
pull/42/head
Martin Bober 1 month ago
parent
commit
ebde464762
  1. 37
      CONTRIBUTING.md
  2. 25
      LICENSE.md
  3. 82
      Readme.md
  4. 81
      doc/Docker.md
  5. 4
      doc/GettingStarted.md

37
CONTRIBUTING.md

@ -0,0 +1,37 @@
# Contributing Guidelines
You want to contribute to the development of charXchange? That's great. But before you submit a pull request (PR), please make sure to read this guide.
## License
Please make sure that you agree to terms and conditions stated in [LICENSE.md](LICENSE.md) before submitting a PR. When submitting a PR it will be assumed that you agree to sharing your code under these terms.
## Branching Strategy
This project follows the [Git Flow](https://www.gitkraken.com/learn/git/git-flow) workflow. The `master` branch is the release branch and `develop` is the branch where the next release is developed. These two branches are protected, meaning most people won't be able to directly push onto them but must use pull requests.
Bugfix and feature branch's names should start with the ticket number, followed by a dash `-` and a short description of the ticket. For example: `feature/42-some-feature`.
## Language
Although charXchange has German and English translations, the project's main language for tickets, (commit) comments and so on should be English.
## PR Acceptance Criteria
### Tests
All automated tests *must* pass. See the [Getting Started Guide](doc/GettingStarted.md) on how to execute the tests locally.
If your PR changes backend behaviour there *should* be a meaningful test in your PR checking that behavior. Normally, the test should fail before the PR is applied and must pass after the patch is applied.
### I18n
All texts that are presented to the user *must* be internationalized. English *and* German localizations *must* be present. If you are having trouble providing the German localization, please feel free to ask other developers for help.
Log messages (Browser JS console messages as well as Rails console messages) should be English only.
### Commit messages
The used commit messages *should* adhere to the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) standard. Although this is more of a best practise than a strictly enforced rule.
Tickets *should* be mentioned in the footer of the commit message, normally in the form: `Refs: #123`. See also [Gitea automatically linked references](https://docs.gitea.io/en-us/automatically-linked-references/).

25
LICENSE.md

@ -0,0 +1,25 @@
The source code is provided under MIT License.
The assets at `app/assets/images` are proprietary assets. Licenses have been bought by Martin Bober to be used in the Pen&PaperBox. If you want to use these files in other instances or projects, **you will have acquire your own licenses.**
## MIT License
Copyright (c) 2022 Martin Bober
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

82
Readme.md

@ -1,81 +1,11 @@
# Docker Image Documentation
# charXchange Full Stack Rails Application
## Configuration
This is the full stack Rails application that powers the [Pen&PaperBox](https://penpaperbox.com).
The following environmental variables are being used:
There is are some other services that the Rails application depends on. To check them out, have a look at [docker-compose.yml](docker-compose.yml).
| Variable | Use |
|----------------------------|-----------------------------------------------------------------------------------------------------------------------|
| RAILS_DB_HOST | MySQL server to use in Production and Development. |
| RAILS_DB_NAME | MxSQL database to use in Production and Development. |
| RAILS_DB_USER | MySQL user name to use in Production and Development. |
| RAILS_DB_PASSWD | MySQL password to use in Production and Development. |
| REDIS_URL | Redis URL to use, i.e. redis://localhost:6379/1 |
| RAILS_REDIS_CHANNEL_PREFIX | Prefix for redis channels, i.e. development or producation |
| SECRET_KEY_BASE | Secret to use in Production |
| RAILS_ENV | Rails environment to use. Defaults to `production`. |
| DICEBOT_URL | URL to use for DiceBot connections from client-side, for example: `https://dicebot.charxchange.com`. |
| DICEBOT_URL_INTERNAL | URL to use for DiceBot connections from charXchange server. Might differ from DICEBOT_URL because of Docker routings. |
| DICEBOT_SECRET | Shared secret with DiceBot. |
| OPEN_GRAPH_PROXY_URL | URL of OpenGraph proxy server to use. |
| MUMBLE_ADDRESS | DNS name or IP of the Mumble Server |
| MUMBLE_WEBSOCK_PORT | (public reachable) port of the Mumble WebSocket interface |
| RAILS_MAILER_METHOD | Method used to deliver mails in production. Should be `test` (default) or `smtp` |
| RAILS_SMTP_SERVER | SMTP server to use for mail delivery. |
| RAILS_SMTP_PORT | Port to use for mail delivery, for example: `25` |
| RAILS_SMTP_DOMAIN | Domain name to signal SMTP server |
| RAILS_SMTP_AUTH_METHOD | Authentication method to use, for examlpe: `login` |
| RAILS_SMTP_USER | User name to use with SMTP authentication. |
| RAILS_SMTP_PASSWD | Password to use with SMTP authentication. |
| RAILS_TEST_DB_HOST | MySQL server to use in Test. |
| RAILS_TEST_DB_NAME | MxSQL database to use in Test. |
| RAILS_TEST_DB_USER | MySQL user name to use in Test. |
| RAILS_TEST_DB_PASSWD | MySQL password to use in Test. |
| PPB_NEW_PLAYER_WELCOME_BY | When set, new players will receive a welcome message from the player with the given ID |
| STUN_URL | URL to a STUN server to be used for P2P streams. Example: `stun.example.com` |
The application is deployed as a Docker image. The documentation of which can be found in the [Docker Image documentation](doc/Docker.md).
## First Start
To get a development instance running locally, check out the [Getting Started Guide](doc/GettingStarted.md).
On first start, you have to start a terminal in the container and run the following command to populate create the database structure.
bin/rake db:schema:load
If your are using a production database backup and encounter errors on import, you might need to modify the charsets in the backup
sed -i charxchange.sql -e 's/utf8mb4_0900_ai_ci/utf8mb4_unicode_ci/g'
## Cron Job
You will need to run the daily cron tasks
rails cron_daily
## RubyMine Integration
### Ruby Remote SDK
Go to `Settings --> Ruby SDK and Gems` and add at least two new Docker Compose Remote SDKs for `development` and `production`.
Make the `development` remote SDK the project's default SDK by selecting it. So all rake commands started with `Ctrl-Alt-R` will execute in that container.
### Run Configurations
First create a new Docker Run Configuration using the Docker Compose file. Ruby mine needs this for not screwing up.
Then go to the existing Rails and Rake run configurations and set the SDK to the appropriate remote SDK.
You might need to disable the Spring preloader for the `test` rake task to work. Do so using `Ctrl-Shift-A` and search for `Spring`.
*Note that the starting a run configuration changes the container's entry point. For example after running a rake task in the `development` container, you will need to re-run the Development run configuration.*
### Database connectors
Go and create the appropriate MySQL database connectors. You will find the access credentials and ports in the [Docker compose file](docker-compose.yml). The host is always `localhost`.
#### Populate database
When you want to restore a backup of the live database, be sure to use the following command:
docker-compose exec development_db mysql -u root -p --one-database charxchange
If data from more than one database is imported, the MySQL container will Exit 1 immediate after next startup.
If you want to get in touch with us, you can open a ticket, join us on [Discord](https://discord.gg/Dp3zr8YVET), [Matrix](https://matrix.to/#/!EhDDSTrmDMwihbTQWj:matrix.mbober.de?via=matrix.mbober.de&via=tchncs.de) or follow us on [Twitter](https://twitter.com/PenPaperBox1).

81
doc/Docker.md

@ -0,0 +1,81 @@
# Docker Image Documentation
## Configuration
The following environmental variables are being used:
| Variable | Use |
|----------------------------|-----------------------------------------------------------------------------------------------------------------------|
| RAILS_DB_HOST | MySQL server to use in Production and Development. |
| RAILS_DB_NAME | MxSQL database to use in Production and Development. |
| RAILS_DB_USER | MySQL user name to use in Production and Development. |
| RAILS_DB_PASSWD | MySQL password to use in Production and Development. |
| REDIS_URL | Redis URL to use, i.e. redis://localhost:6379/1 |
| RAILS_REDIS_CHANNEL_PREFIX | Prefix for redis channels, i.e. development or producation |
| SECRET_KEY_BASE | Secret to use in Production |
| RAILS_ENV | Rails environment to use. Defaults to `production`. |
| DICEBOT_URL | URL to use for DiceBot connections from client-side, for example: `https://dicebot.charxchange.com`. |
| DICEBOT_URL_INTERNAL | URL to use for DiceBot connections from charXchange server. Might differ from DICEBOT_URL because of Docker routings. |
| DICEBOT_SECRET | Shared secret with DiceBot. |
| OPEN_GRAPH_PROXY_URL | URL of OpenGraph proxy server to use. |
| MUMBLE_ADDRESS | DNS name or IP of the Mumble Server |
| MUMBLE_WEBSOCK_PORT | (public reachable) port of the Mumble WebSocket interface |
| RAILS_MAILER_METHOD | Method used to deliver mails in production. Should be `test` (default) or `smtp` |
| RAILS_SMTP_SERVER | SMTP server to use for mail delivery. |
| RAILS_SMTP_PORT | Port to use for mail delivery, for example: `25` |
| RAILS_SMTP_DOMAIN | Domain name to signal SMTP server |
| RAILS_SMTP_AUTH_METHOD | Authentication method to use, for examlpe: `login` |
| RAILS_SMTP_USER | User name to use with SMTP authentication. |
| RAILS_SMTP_PASSWD | Password to use with SMTP authentication. |
| RAILS_TEST_DB_HOST | MySQL server to use in Test. |
| RAILS_TEST_DB_NAME | MxSQL database to use in Test. |
| RAILS_TEST_DB_USER | MySQL user name to use in Test. |
| RAILS_TEST_DB_PASSWD | MySQL password to use in Test. |
| PPB_NEW_PLAYER_WELCOME_BY | When set, new players will receive a welcome message from the player with the given ID |
| STUN_URL | URL to a STUN server to be used for P2P streams. Example: `stun.example.com` |
## First Start
On first start, you have to start a terminal in the container and run the following command to populate create the database structure.
bin/rake db:schema:load
If your are using a production database backup and encounter errors on import, you might need to modify the charsets in the backup
sed -i charxchange.sql -e 's/utf8mb4_0900_ai_ci/utf8mb4_unicode_ci/g'
## Cron Job
You will need to run the daily cron tasks
rails cron_daily
## RubyMine Integration
### Ruby Remote SDK
Go to `Settings --> Ruby SDK and Gems` and add at least two new Docker Compose Remote SDKs for `development` and `production`.
Make the `development` remote SDK the project's default SDK by selecting it. So all rake commands started with `Ctrl-Alt-R` will execute in that container.
### Run Configurations
First create a new Docker Run Configuration using the Docker Compose file. Ruby mine needs this for not screwing up.
Then go to the existing Rails and Rake run configurations and set the SDK to the appropriate remote SDK.
You might need to disable the Spring preloader for the `test` rake task to work. Do so using `Ctrl-Shift-A` and search for `Spring`.
*Note that the starting a run configuration changes the container's entry point. For example after running a rake task in the `development` container, you will need to re-run the Development run configuration.*
### Database connectors
Go and create the appropriate MySQL database connectors. You will find the access credentials and ports in the [Docker compose file](docker-compose.yml). The host is always `localhost`.
#### Populate database
When you want to restore a backup of the live database, be sure to use the following command:
docker-compose exec development_db mysql -u root -p --one-database charxchange
If data from more than one database is imported, the MySQL container will Exit 1 immediate after next startup.

4
doc/GettingStarted.md

@ -75,5 +75,9 @@ To actually run the test execute:
sudo docker-compose exec test rails test
## What's next
If you want to contribute to the development of the charXchange project, you should check out our [Contributing Guide](../CONTRIBUTING.md)
[docker]: https://docs.docker.com/desktop/get-started/
[docker-compose]: https://docs.docker.com/compose/
Loading…
Cancel
Save