From 7e67f8de7b7444b06123a33e02464ef1fc6e082c Mon Sep 17 00:00:00 2001 From: shibao Date: Mon, 31 Jan 2022 20:04:38 -0500 Subject: [PATCH] add contributing guide --- CONTRIBUTING.md | 85 +++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 63 +++++++++++++++++++----------------- 2 files changed, 118 insertions(+), 30 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..4cd291ca --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,85 @@ +# Contribution Guide + +Thanks for contributing to Cannery! Please read over the style tips to help make +contributing to Cannery (hopefully) as great of an experience as you found it! + +## Tips + +- In order to cut down on code verbosity and readability, please try to use + inline `do:` blocks for short functions and make your aliases as short as + possible without introducing ambiguity. + - I.e. since there's only one `Changeset` in the app, please alias + `Changeset.t()` instead of using `Ecto.Changeset.t()` +- Use pipelines when possible. If a function only calls a single method, a + pipeline isn't strictly necessary but still encouraged for future + modification. +- Please add typespecs to your functions! Even your private functions may be + used by others later down the line, and typespecs will be able to help + document your code just a little bit better, and improve the debugging + process. + - Typespec arguments can be named like `@spec function(arg_name :: type()) :: + return_type()`. Please use these for generic types, such as `map()` when the + input data isn't immediately obvious. +- When making new models, please take inspiration from the existing models in + regards to layout of sections, typespec design, and formatting. +- With Elixir convention, for methods that raise on error please name them like + `function_that_raises!()`, and functions that return a boolean like + `function_that_returns_boolean?()`. For other methods, it's encouraged to use + status tuples for other functions like `{:ok, result}` or `{:error, + reason_or_changeset}` instead of just returning `result` or `nil` for easy + pattern matching. +- Before submitting a PR, please make sure all tests are passing using `mix test`. + +And as always, thank you! + +# Features + +- Created using the [Phoenix Framework](https://www.phoenixframework.org) +- User Registration/Sign in via [`phx_gen_auth`](https://hexdocs.pm/phx_gen_auth/). +- `Dockerfile` and example `docker-compose.yml` +- Automatic migrations in `MIX_ENV=prod` or Docker image +- JS linting with [standard.js](https://standardjs.com), HEEx linting with + [heex_formatter](https://github.com/feliperenan/heex_formatter) + +# Instructions + +1. Clone the repo +1. Install the elixir and erlang binaries. I recommend using [asdf version + manager](https://asdf-vm.com/guide/getting-started.html#_1-install-dependencies), + which will use the `.tool-versions` file to install the correct versions of + Erlang, Elixir and npm for this project! +1. Run `mix deps.get` and `mix compile` to fetch all dependencies +1. Run `mix setup` to initialize your database. +1. Run `mix phx.server` to start the development server. + +# Configuration + +For development, I recommend setting environment variables with [direnv](https://direnv.net). + +## `MIX_ENV=dev` + +In `dev` mode, Cannery will listen for these environment variables on compile. + +- `HOST`: External url to generate links with. Set these especially if you're + behind a reverse proxy. Defaults to `localhost`. +- `PORT`: External port for urls. Defaults to `443`. +- `DATABASE_URL`: Controls the database url to connect to. Defaults to + `ecto://postgres:postgres@localhost/cannery_dev`. +- `REGISTRATION`: Controls if user sign-up should be invite only or set to public. Set to `public` to enable public registration. Defaults to `invite`. + +## `MIX_ENV=prod` + +In `prod` mode (or in the Docker container), Cannery will listen for these environment variables at runtime. + +- `HOST`: External url to generate links with. Set these especially if you're + behind a reverse proxy. Defaults to `localhost`. +- `PORT`: Internal port to bind to. Defaults to `80` and attempts to bind to + `0.0.0.0`. Must be reverse proxied! +- `DATABASE_URL`: Controls the database url to connect to. Defaults to + `ecto://postgres:postgres@cannery-db/cannery`. +- `ECTO_IPV6`: Controls if Ecto should use ipv6 to connect to PostgreSQL. + Defaults to `false`. +- `POOL_SIZE`: Controls the pool size to use with PostgreSQL. Defaults to `10`. +- `SECRET_KEY_BASE`: Secret key base used to sign cookies. Must be generated + with `mix phx.gen.secret` and set for server to start. +- `REGISTRATION`: Controls if user sign-up should be invite only or set to public. Set to `public` to enable public registration. Defaults to `invite`. diff --git a/README.md b/README.md index fac31d8e..9d1bc38f 100644 --- a/README.md +++ b/README.md @@ -6,47 +6,43 @@ # Features -- User Registration/Sign in via `phx_gen_auth` -- `Dockerfile` and example `docker-compose.yml` -- Automatic migrations in `MIX_ENV=prod` or Docker image -- JS linting with [standard.js](https://standardjs.com), HEEx linting with - [heex_formatter](https://github.com/feliperenan/heex_formatter) -- Customizable invite tokens or public registration via `REGISTRATION` +- Create containers to store your ammunition, and tag them with custom tags +- Add ammunition types to Cannery, and then ammunition to your containers +- Customizable invite tokens or public registration via the `REGISTRATION` environment variable. # Installation 1. Install [Docker Compose](https://docs.docker.com/compose/install/) or alternatively [Docker Desktop](https://docs.docker.com/desktop/) on your machine. -1. Copy the example `docker-compose.yml` into your local machine where you want +1. Copy the example `docker-compose.yml` into your local machine where you want. + Bind mounts are created in the same directory by default. +1. Use `docker-compose up` or `docker-compose up -d` to start the container. -# Local Development +## Reverse proxy -1. Clone the repo -2. Run `mix setup` -3. Run `mix phx.server` to start the development server +Finally, reverse proxy to port `80` of the container. If you're using a reverse proxy in another docker container, you can reverse proxy to `http://cannery:80`. Otherwise, you'll need to modify the `docker-compose.yml` to bind the port to your local machine. + +For instance, instead of +``` +expose: + - "80" +``` + +use +``` +ports: + - "127.0.0.1:80:80" +``` +and reverse proxy to `http://localhost:80`. # Configuration -For development, I recommend setting environment variables with [direnv](https://direnv.net). - -## `MIX_ENV=dev` - -In `dev` mode, Cannery will listen for these environment variables on compile. +You can use the following environment variables to configure Cannery in +`docker-compose.yml`. - `HOST`: External url to generate links with. Set these especially if you're behind a reverse proxy. Defaults to `localhost`. -- `PORT`: External port for urls. Defaults to `443`. -- `DATABASE_URL`: Controls the database url to connect to. Defaults to - `ecto://postgres:postgres@localhost/cannery_dev`. -- `REGISTRATION`: Controls if user sign-up should be invite only or set to public. Set to `public` to enable public registration. Defaults to `invite`. - -## `MIX_ENV=prod` - -In `prod` mode (or in the Docker container), Cannery will listen for these environment variables at runtime. - -- `HOST`: External url to generate links with. Set these especially if you're - behind a reverse proxy. Defaults to `localhost`. -- `PORT`: Internal port to bind to. Defaults to `4000` and attempts to bind to +- `PORT`: Internal port to bind to. Defaults to `80` and attempts to bind to `0.0.0.0`. Must be reverse proxied! - `DATABASE_URL`: Controls the database url to connect to. Defaults to `ecto://postgres:postgres@cannery-db/cannery`. @@ -54,10 +50,17 @@ In `prod` mode (or in the Docker container), Cannery will listen for these envir Defaults to `false`. - `POOL_SIZE`: Controls the pool size to use with PostgreSQL. Defaults to `10`. - `SECRET_KEY_BASE`: Secret key base used to sign cookies. Must be generated - with `mix phx.gen.secret` and set for server to start. + with `docker exec -it cannery mix phx.gen.secret` and set for server to start. - `REGISTRATION`: Controls if user sign-up should be invite only or set to public. Set to `public` to enable public registration. Defaults to `invite`. ---- +# Contribution + +Contributions are greatly appreciated! You can browse the [Contribution Guide](CONTRIBUTING.md) to learn more. + +I can be contacted at [shibao@bubbletea.dev](mailto:shibao@bubbletea.dev), or on +the fediverse at [@shibao@misskey.bubbletea.dev](https://misskey.bubbletea.dev/@shibao). Thank you! + +-- [![Build Status](https://drone.bubbletea.dev/api/badges/shibao/cannery/status.svg?ref=refs/heads/dev)](https://drone.bubbletea.dev/shibao/cannery)