Commit ba1d89f2 authored by hellekin's avatar hellekin

Add basic documentation

parent f2b0a76d
# INCOMMON Database Setup
The `incommon-api` database uses [PostgreSQL] 10 with [PostGIS] extensions.
[PostgreSQL]: https://www.postgresql.org/ "The World's Most Advanced Open Source Relational Database"
[PostGIS]: https://postgis.net/ "Spatial and Geographic objects for PostgreSQL"
## Backup & Restore
### Backup
The database structure is saved in `db/structure.sql` when you run `rails db:migrate`.
Data can be saved with:
``` shell
pg_dump --column-insert --data-only -d $DB_NAME | gzip -9 - > db/incommon_data.`date +%F`.sql.gz
```
This should be performed on a regular basis, e.g., daily in a crontab:
```
PATH=/bin:/usr/bin
# Backup IN COMMON database every day at 02:04 AM
4 2 * * * pg_dump --column-insert --data-only -d incommon-api | gzip -9 - > db/incommon_data.`date +%F`.sql.gz
```
### Restore
In order to restore data from a backup, it's better to drop the existing
database and follow the instructions in the Production section below.
In a nutshell, from an existing backup file:
``` shell
zcat db/incommon_data.2018-10-01.sql.gz | psql -d incommon-api -u $INCOMMON_API_DB_USER -p
```
## Development
``` shell
bundle exec rails db:setup
```
### Resetting the database
You can restore the database to its pristine state, or recreate it from scratch
if you have new migrations. If you do not have new migrations, you could instead
run `bundle exec rails db:reset`, as it will recreate the database not from
migrations but from the `db/structure.sql` file.
``` shell
bundle exec rails db:drop
bundle exec rails db:setup
bundle exec rails db:migrate
```
## Production
This must be run once when first deploying the `incommon-api`: it will create
the database and user role, then import the raw data from a backup: here
`2018-10-01` is an example date! Copy the right filename from `db/` instead.
``` shell
INCOMMON_API_DB_USER=someuser INCOMMON_API_DB_PASS=somestrongsecret RAILS_ENV=production \
bundle exec rails db:setup
zcat db/incommon_data.2018-10-01.sql.gz | psql -d incommon-api -u $INCOMMON_API_DB_USER -p
```
# I18n -- Localizing IN COMMON
Default language is English (en) and original locale file can be found in
`config/locales/en.yml`.
## Rails introduction
Files in the config/locales directory are used for internationalization and are
automatically loaded by Rails. If you want to use locales other than English,
add the necessary files in this directory.
To use the locales, use `I18n.t`:
I18n.t 'hello'
In views, this is aliased to just `t`:
<%= t('hello') %>
To use a different locale, set it with `I18n.locale`:
I18n.locale = :es
This would use the information in config/locales/es.yml.
The following keys must be escaped otherwise they will not be retrieved by
the default I18n backend:
true, false, on, off, yes, no
Instead, surround them with single quotes.
en:
'true': 'foo'
To learn more, please read the Rails Internationalization guide available at
http://guides.rubyonrails.org/i18n.html.
# INCOMMON Models
## High-Level
### Map
### Resource
### Taxonomy
## Classifications
### Taxonomy
``` shell
rails g model Taxonomy name:string\{64\}:unique summary:string\{136\} \
description:text uuid:uuid:unique agent:references categories_count:integer\{2\}
```
### Category
``` shell
rails g model Category name:string\{64\} summary:string\{136\} \
description:text taxonomy:references sections_count:integer\{3\}
```
### Section
```shell
rails g model Section name:string\{80\} summary:string\{136\} \
description:text category:references resources_count:integer
```
## Descriptors
### Event
### Location
### Tagging
## Generic
### Position
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment