README.md 6.69 KB
Newer Older
1
### INK
2

3
Ink is an API. It provides an extensible step-based framework for file conversions as a first use case, but is intended to be a more generalised framework for all kinds of steps needed when preparing materials for publication.
4

charlie-ablett's avatar
charlie-ablett committed
5
## Ruby version
6
7
8

2.2.3

charlie-ablett's avatar
charlie-ablett committed
9
## Rails version
10

11
12
It uses Rails 5 in API version.

Alf Eaton's avatar
Alf Eaton committed
13
## Setup with Docker (recommended)
14

Alf Eaton's avatar
Alf Eaton committed
15
16
Follow [the official instructions](https://docs.docker.com/compose/install/) for installation of Docker and Docker Compose.

17
18
(optional) If your INK steps have Docker dependencies, add those services to a `docker-compose.override.yml` file in this directory.

Alf Eaton's avatar
Alf Eaton committed
19
20
Run `docker volume create --name=gems` to create a Docker volume for storing the Ruby gem dependencies outside the container.

Aanand Prasad's avatar
Aanand Prasad committed
21
Run `docker-compose up` to start the app.
Alf Eaton's avatar
Alf Eaton committed
22
23

The INK API is now running. See [ink-client](https://gitlab.coko.foundation/INK/ink-client/) for a React front-end for creating and managing recipes.
24

Aanand Prasad's avatar
Aanand Prasad committed
25
26
## Run tests

Aanand Prasad's avatar
Aanand Prasad committed
27
Run `script/test` to run the tests in a Docker container. You can pass files or directories as arguments to scope the run to particular tests:
Aanand Prasad's avatar
Aanand Prasad committed
28

Aanand Prasad's avatar
Aanand Prasad committed
29
30
    script/test spec/models
    script/test spec/controllers/v1/admin_controller_spec.rb
Aanand Prasad's avatar
Aanand Prasad committed
31

vasilis's avatar
vasilis committed
32
## Setup gitlab CI
33
34

Go to /admin/runners on gitlab and copy the ci token.
vasilis's avatar
vasilis committed
35

36
Go to an accessible server and install a gitlab runner https://docs.gitlab.com/runner/
vasilis's avatar
vasilis committed
37

vasilis's avatar
vasilis committed
38
Make sure the runner's host has docker-engine installed
vasilis's avatar
vasilis committed
39

40
Register the runner with the ci token
vasilis's avatar
vasilis committed
41

vasilis's avatar
vasilis committed
42
  Choose docker+machine as executor type and docker:latest as the image
vasilis's avatar
vasilis committed
43

vasilis's avatar
vasilis committed
44
45
  You can do this with this command
  `gitlab-runner register -n -u $GITLAB_CI_URL --docker-image docker:latest -r $GITLAB_TOKEN --executor docker+machine --docker-privileged`
vasilis's avatar
vasilis committed
46
47

Now whenever you push to the repo the rspec tests will run.
48

49

50
## Setup (for developers)
51

52
53
Linux (debian/ubuntu)

54
55
Install `rbenv` (recommended) or `rvm` and install the required ruby version (see `.ruby-version.rb`)

charlie-ablett's avatar
charlie-ablett committed
56
Make sure postgres is installed (recommended 9.1+, minimum 8.2)
57

vasilis's avatar
vasilis committed
58
59
60
61
62
63
Copy the .env.sample file to .env

Fill the .env file variables with your values

Run `eval $(cat .env | sed 's/^/export /')` to export the variables to the environment

vasilis's avatar
vasilis committed
64
~~Copy the `config/database.yml.sample` file into `config/database.yml` and change the credentials to match whatever postgres setup you have.~~
65

vasilis's avatar
vasilis committed
66
~~Copy the `config/ink_api.yml.sample` file into `config/ink_api.yml` and put in the storage directory you'd like to use for files.~~
67

68
69
In the project directory (e.g. `/usr/you/ink-api`), run `gem install bundler` and `gem install rake` if you need to

70
71
Copy `StepGemfile.sample` and name the copy `StepGemfile`.

72
73
74
Run `bundle install` to install the required gems.

Run `bundle exec rake db:create` to create the database, then `bundle exec rake db:schema:load` to create all the tables. If you have any issues, check `config/database.yml` to ensure the credentials are correct.
75

charlie-ablett's avatar
charlie-ablett committed
76
77
78
Run the seeds `bundle exec rake db:seed` for some sample recipes and a sample account and service.

If you want to add some custom accounts, run the rake task for creating an account (see `lib/tasks/setup.rake`). You can always use `bundle exec rails console`.
79
80
81
82
83
84
85

### Install 'slanger'

Go to [the Slanger homepage](https://github.com/stevegraham/slanger) and install it according to the 'server setup' directions.

The Slanger web service uses localhost port 4444 by default, but this can be changed by setting the `SLANGER-PORT` and 'SLANGER-SERVER' env variables

86
87
Run slanger (replace variables APP_KEY, SECRET, ADDRESS and PORT): `slanger --app_key APP_KEY --secret SECRET -w ADDRESS:PORT`. For development, you can use the command `slanger --app_key 44332211ffeeddccbbaa --secret aabbccddeeff11223344 -a localhost:4567 -w localhost:4444 --verbose` (the `--verbose` tag will help you debug if you need it).

88
89
## Setup (for production)

90
In addition to the above, on the server:
91
92
93
94

- Set up an environment variable as per `secrets.yml` for Devise token auth.
- Set up nginx and passenger to act as web server.

95
96
Copy the `env.sample` file into `.env`. Populate with the environment variables needed in the `deployable_settings` bit.

97
98
Copy the `StepGemfile.sample` file into `StepGemfile`. Add any step gems you'd like to include (there are some there to get you started)

99
100
Run slanger on the target server (replace APP_KEY, SECRET, ADDRESS and PORT): `slanger --app_key APP_KEY --secret SECRET -w ADDRESS:PORT`. For development, you can use the command `slanger --app_key 44332211ffeeddccbbaa --secret aabbccddeeff11223344 -a 0.0.0.0:4567 -w 0.0.0.0:4444 --verbose` (the `--verbose` tag will help you debug if you need it).

101
102
### Step Third-party Binary Dependencies

103
These are listed under the gem readme files for the appropriate step gems.
104

105
### Run it
106

charlie-ablett's avatar
charlie-ablett committed
107
108
109
Run the Rails server in a terminal - `bundle exec rails s`

Run redis in another terminal - `redis-server`
110

charlie-ablett's avatar
charlie-ablett committed
111
Run sidekiq in another terminal - `bundle exec sidekiq`
112

charlie's avatar
charlie committed
113
Check `localhost:3000/api/anyone` to see if it's up.
114

115
116
Once it is up and running, run the rake task in `lib/setup.rake` to create some users.

117
118
119
120
121
122
123
124
125
126
### Adding a new step gem to the server

Modify the `StepGemfile` (or make one if you don't have one already - there's a `StepGemfile.sample` to copy)
The dependencies are handled by Bundler, so be aware that there may be version incompatibilities if ink-api and a step gem require different versions of the same dependency. 
In most cases, Bundler cna handle this by itself, but it may take some fiddling by you to get it right.

Run `bundle install`

Restart the server on production by running `touch $rails_root/tmp/restart.txt`. Replace `$rails_root` with your Rails root directory (where the Gemfile is)

127
## Further development
128

129
### Adding a new step
130

131
To write a new step, create a gem (you can host it under RubyGems). I've included code so that the step files get autoloaded when Rails is present.
132

charlie-ablett's avatar
charlie-ablett committed
133
The example I'll use here is `InkStep::Coko::RotThirteen` included in the gem `coko_demo_steps`.
134
135
136

You can install in a few ways:

137
Via StepGemfile. Include the line `gem 'coko_demo_steps', git: 'git@gitlab.coko.foundation:INK/coko_demo_steps.git` and run `bundle install`.
138

139
### Upgrading API version
140
141
142
143
144
145
146
147

To prevent breaking consumers of this API with upgrades, this API is versioned with a simple mechanism that looks for the API version specified in the request header.

To add a new API version (Assuming upgrading from v1 to v2):

* Copy the routes in `config/routes` to add `v2` and set it as the default.

* Copy the following directories and call the copy `v2`
charlie-ablett's avatar
charlie-ablett committed
148
149
150
  * `controllers/api/v1`
  * `spec/controllers/v1`
  * `spec/features/v1`
151

152
153
In each of these, you'll have to rename the `V1` module to `V2`.
Open `spec/controllers/v1/version.rb` and `spec/integration/v1/version.rb` Change the version in your copy to `v2`.
154

charlie-ablett's avatar
charlie-ablett committed
155
## Support
156

157
Contact charlie@coko.foundation for all your (ink-related) support needs.
158

charlie-ablett's avatar
charlie-ablett committed
159
## License
160

161
MIT.