Skip to content

Commit

Permalink
docs: add quick contributing instructions
Browse files Browse the repository at this point in the history
  • Loading branch information
adamcooke committed Feb 23, 2024
1 parent dc8e895 commit 8d21adc
Show file tree
Hide file tree
Showing 2 changed files with 87 additions and 0 deletions.
49 changes: 49 additions & 0 deletions CONTRIBUTING.md
@@ -0,0 +1,49 @@
# Contributing to Postal

This doc explains how to go about running Postal in development to allow you to make contributions to the project.

## Dependencies

You will need a MySQL database server to get started. Postal needs to be able to make databases within that server whenever new mail servers are created so the permissions that you use should be suitable for that.

You'll also need Ruby. Postal currently uses Ruby 3.2.1. Install that using whichever version manager takes your fancy - rbenv, asdf, rvm etc.

## Clone

You'll need to clone the repository

```
git clone git@github.com:postalserver/postal
```

Once cloned, you can install the Ruby dependencies using bundler.

```
bundle install
```

## Configuration

At present, configuration is handled using a config file. This lives in `config/postal/postal.yml`. An example configuration file is provided in `config/postal.example.yml`. This example is for development use only and not an example for production use.

You'll also need a key for signing. You can generate one of these like this:

```
openssl genrsa -out config/postal/signing.key 2048
```

## Running

The neatest way to run postal is to ensure that `./bin` is your `$PATH` and then use one of the following commands.

* `bin/dev` - will run all components of the application using Foreman
* `bin/postal` - will run the Postal binary providing access to running individual components or other tools.

## Database initialization

Use the commands below to initialize your database and make your first user.

```
postal initialize
postal make-user
```
38 changes: 38 additions & 0 deletions config/postal.example.yml
@@ -0,0 +1,38 @@
web:
host: postal.example.dev
protocol: https

web_server:
bind_address: 0.0.0.0
port: 4010

smtp_server:
port: 2525

logging:
rails_log: true
stdout: true

main_db:
host: 127.0.0.1
username: root
password:
database: postal

message_db:
host: 127.0.0.1
username: root
password:
prefix: postal

smtp:
host: 127.0.0.1
port: 2525
username:
password:
from_name: Postal
from_address: postal@yourdomain.com

rails:
environment: development
secret_key: 7f27856d26e864bafd49d0df37ad3d1339086e86ef0447e0f1814dde5277452fea97dab9e3aad6dfa11bfe359c82ce302d97bf1e58f6103c4408e4fbad4eeccf

0 comments on commit 8d21adc

Please sign in to comment.