README.md 5.52 KB
Newer Older
hellekin's avatar
hellekin committed
1
# IN COMMON API
2

hellekin's avatar
hellekin committed
3 4 5 6
1. [Introduction & Usage](#intro)
2. [Installation & Configuration](#install)
3. [Contributing & Reporting](#contribute)
4. [Licensing](#license)
hellekin's avatar
hellekin committed
7
5. [Community](https://talk.incommon.cc) & [Support](https://talk.incommon.cc/c/api/support)
hellekin's avatar
hellekin committed
8 9 10 11 12


<a name="intro"></a>

## [Introduction](https://api.incommon.cc/intro) & Usage
13

hellekin's avatar
hellekin committed
14
[![pipeline status](https://gitlab.com/incommon.cc/incommon-api/badges/master/pipeline.svg)](https://gitlab.com/incommon.cc/incommon-api/commits/master)
15

hellekin's avatar
hellekin committed
16
[![coverage report](https://gitlab.com/incommon.cc/incommon-api/badges/master/coverage.svg)](https://gitlab.com/incommon.cc/incommon-api/commits/master)
17

hellekin's avatar
hellekin committed
18 19
This is a Rails 5 API-only application using Ruby 2.5.3 (MRI) and PostgreSQL 10
with PostGIS extensions.
20

hellekin's avatar
hellekin committed
21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44
### Usage

**Always use an API key**. The default, public API key is: `23d8009f-f2ec-44b6-bcbe-58ad1d3af10b`.

In your requests to the IN COMMON API, you can use it as a query parameter:

``` shell
curl https://api.incommon.cc/?api_key=23d8009f-f2ec-44b6-bcbe-58ad1d3af10b
```


<a name="install"></a>

## Installation & Configuration

1. [System Dependencies](#system-dependencies)
2. [Configuration](#configuration)
3. [Testing](#testing)
4. [Services](#services)
5. [Deployment](#deployment)


<a name="system-dependencies"></a>

hellekin's avatar
hellekin committed
45
### System Dependencies
46

hellekin's avatar
hellekin committed
47 48
It is developped on Gentoo / GNU/Linux and should support any GNU/Linux system
in production. For Ruby, we recommend using [ruby-install] and [chruby]!
49

hellekin's avatar
hellekin committed
50 51
[ruby-install]: https://github.com/postmodern/ruby-install
[chruby]: https://github.com/postmodern/chruby
52

hellekin's avatar
hellekin committed
53 54 55

<a name="configuration"></a>

hellekin's avatar
hellekin committed
56
### Configuration
57

hellekin's avatar
hellekin committed
58
Examples show the case of Debian-based systems. <abbr title="Your Mileage May Vary">YMMV</abbr>.
59

hellekin's avatar
hellekin committed
60
#### NginX + Puma
61

hellekin's avatar
hellekin committed
62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110
Local development is setup to use Puma with sockets. 

If you don't have `sudo` access, consider changing Puma configuration from:

`bind "unix://#{shared_dir}/sockets/puma.sock";` to: `bind "tcp://127.0.0.1:3001/";`

And skip this step :)

See [doc/development/nginx.conf] for a sample developer configuration. With this
setup you should add an entry in your `/etc/hosts`:

``` shell
echo '127.0.0.1 api.example.net' | sudo tee -a /etc/hosts
```

[doc/development/nginx.conf]: ../doc/development/nginx.conf

#### PostgreSQL + PostGIS

We use PostgreSQL 10. Enable PostGIS extensions (or ask your system administrator to do so).

`sudo apt install postgresql-10 postgis`

Your current database user should be authorized in PostgreSQL. If not, you should enable it:

``` shell
cat <<DB_ACCESS | sudo tee -a $PATH_TO_PG_HBA_CONF
# TYPE  DATABASE        USER            ADDRESS                 METHOD
local   $INCOMMON_DB_NAME $INCOMMON_DB_USER                     md5
DB_ACCESS

```

In the above snippet...

| Replace                 | With...
|-|-
| `$INCOMMON_API_DB_NAME` | your actual database name (e.g., `incommon-api`)
| `$INCOMMON_API_DB_USER` | your actual database user name (e.g., `rails`)
| `$PATH_TO_PG_HBA_CONF`  | On Debian-based systems: `/etc/postgresql/10/main/pg_hba.conf`

Then reload PostgreSQL server: `sudo /etc/init.d/postgresql reload`

##### Loading the database

Please refer to [doc/database_setup.md].

[doc/database_setup.md]: ../doc/database_setup.md

hellekin's avatar
hellekin committed
111 112 113

<a name="testing"></a>

hellekin's avatar
hellekin committed
114 115 116 117 118 119 120 121 122 123
### Testing

We recommend using Guard: `bundle exec guard`.

You can run the specification suite with: `bundle exec rspec`.

Please refer to [RSpec documentation] to run or write individual tests.

[RSpec documentation]: http://rspec.info/documentation/3.8/rspec-core/

hellekin's avatar
hellekin committed
124 125 126

<a name="services"></a>

hellekin's avatar
hellekin committed
127 128
### Services

hellekin's avatar
hellekin committed
129
Writing to the database **will** use Job queues running [Sidekiq] (or similar).
hellekin's avatar
hellekin committed
130 131 132

[Sidekiq]: https://github.com/mperham/sidekiq

hellekin's avatar
hellekin committed
133 134 135

<a name="deployment"></a>

hellekin's avatar
hellekin committed
136 137 138 139 140 141 142 143 144 145 146 147
### Deployment

- always use `db/structure.sql` and database import to get started. It will save
  you some headaches.
- use sockets! They're faster and more secure.
- deploy version tags (`git tag -l | tail -1`)
- **always enable TLS**: the API assumes the connection to the server is
  secure. Not doing so will leak API keys and authentication tokens. You've been
  warned. [LetsEncrypt] gives you gratis SSL certificates.

[LetsEncrypt]: https://letsencrypt.org/

hellekin's avatar
hellekin committed
148 149 150 151

<a name="contribute"></a>

## Contributing & Reporting
hellekin's avatar
hellekin committed
152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169

We're a welcoming community. We expect every contributor to be respectful of
each other and the [IN COMMON Charter].

Our main development SCM goes to <https://framagit.org/incommon.cc/incommon-api>.

It is mirrored to [Gitlab] and [Github].

[IN COMMON Charter]: https://talk.incommon.cc/incommon-charter
[Gitlab]: https://gitlab.com/incommon.cc/incommon-api
[Github]: https://github.com/moners/incommon-api

Our development community gathers at <https://talk.incommon.cc/c/api>.

### Reporting Security Issues

See <https://talk.incommon.cc/t/welcome-developers/127/1>

hellekin's avatar
hellekin committed
170 171 172

<a name="license"></a>

hellekin's avatar
hellekin committed
173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189
## Licensing

`incommon-api` Copyright © 2018 [IN COMMON Collective] and contributors.

This program is free software: you can redistribute it and/or modify it under
the terms of the GNU Affero General Public License as published by the Free
Software Foundation, either version 3 of the License, or (at your option) any
later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along
with this program.  If not, see <https://www.gnu.org/licenses/>.

See [LICENSE](../LICENSE.md)
hellekin's avatar
hellekin committed
190 191

[IN COMMON Collective]: https://talk.incommon.cc/groups/incommon