Установка и использование BaasBox в Ubuntu 14.04

Published by Leave your thoughts

BaasBox – это приложение, которое комбинирует сервер баз данных и сервер приложений. «Из коробки» BaasBox предоставляет аутентификацию пользователей, резервное копирование, а также управление пользователями, ролями, контентом, файлами, базами данных. Поскольку все эти функции предоставляются через стандартный HTTP REST API, BaasBox можно использовать при разработке мобильных и веб-приложений в качестве бэкенда для хранения данных. Также разработчики могут создавать основанные на BaasBox микросервисы, которые можно использовать в качестве компонентов других приложений.

Данное руководство научит устанавливать BaasBox, создавать пользователей, работать с консолью администратора и использовать REST API при разработке простого приложения.

Требования

  • Сервер Ubuntu 14.04.
  • Не-root пользователь с привилегиями администратора (о создании такого пользователя можно прочитать здесь).
  • Предустановленный Java 8 JRE с Oracle (инструкции по установке — в этой статье).

1: Установка и запуск BaasBox

Чтобы установить BaasBox, загрузите последнюю версию программы с официального сайта.

wget http://www.baasbox.com/download/baasbox-stable.zip

С помощью unzip распакуйте полученный архив BaasBox. Если команда unzip не установлена, установите её:

sudo apt-get install unzip

Чтобы распаковать zip-файл, введите:

unzip baasbox-stable.zip

Эта команда извлечёт содержимое архива в каталог baasbox-X.Y.Z, где X.Y.Z — последняя версия программы (в данном случае 0.9.5). Откройте новый каталог:

cd baasbox-X.Y.Z

В каталоге найдите файл start, с помощью которого запускается BaasBox. Сделайте файл исполняемым:

chmod +x ./start

Чтобы запустить BaasBox, введите:

./start

Команда вернёт такой вывод:

2016-06-28 14:32:14,554 - [info] - BaasBox is Ready.
2016-06-28 14:32:14,558 - [info] - Application started (Prod)
2016-06-28 14:32:14,733 - [info] - Listening for HTTP on /0:0:0:0:0:0:0:0:9000
2016-06-28 14:32:15,261 - [info] - Session Cleaner: started
2016-06-28 14:32:15,263 - [info] - Session cleaner: tokens: 0 - removed: 0
2016-06-28 14:32:15,263 - [info] - Session cleaner: finished

Выделенная красным строка значит, что приложение BaasBox запущено и доступно на порте 9000. По умолчанию BaasBox слушает этот порт на всех сетевых интерфейсах. Доступ к BaasBox можно получить по ссылкам:

  • http://localhost:9000 и http://127.0.0.1:9000 (с сервера, на котором установлено приложение, или через SSH-туннель).
  • http://внутренний_ip_сервера:9000 (во внутренней сети сервера, если такая сеть есть).
  • http://ip_сервера:9000 (через интернет, если ваш ip доступен в интернете).

Примечание: BaasBox можно настроить для прослушивания другого порта на определенном сетевом интерфейсе. Для этого используйте следующую команду:

./start -Dhttp.port=целевой_порт -Dhttp.address=целевой_интерфейс

Консоль администратора BaasBox доступна по ссылке:

http://your_ip_address:9000/console

Теперь нужно настроить приложение и создать пользователей.

2: Создание приложения с помощью BaasBox

В этой статье используется простой менеджер списков задач, который позволит пользователям:

  • подписываться;
  • проходить аутентификацию;
  • создавать несколько списков задач;
  • извлекать свои списки задач;
  • редактировать свои списки задач;
  • удалять списки задач;
  • обмениваться списками задач с другими пользователями.

Примечание: В руководстве используются следующие условные данные:

  • Два пользователя, user1 и user2.
  • Пароли user1_password и user2_password соответственно.
  • ID сессий user1_session_id и user2_session_id соответственно.

BaasBox можно управлять с помощью REST API, но иногда удобнее использовать для этого консоль администратора (по ссылке http://your_ip_address:9000/console). Откройте эту ссылку в браузере и введите учётные данные по умолчанию:

  • Имя пользователя: admin
  • Пароль: admin
  • Код приложения: 1234567890

После этого вы получите доступ к панели инструментов BaasBox.

Создайте пользователей приложения с помощью консоли администратора.

3: Создание пользователей

Управление пользователями — одна из самых полезных функций BaasBox. BaasBox имеет несколько стандартных пользователей, они являются частными и их нельзя редактировать. К таким пользователям относится и администратор, с помощью которого можно получить доступ к консоли.

Также BaasBox позволяет определять роли и присваивать их пользователям. Это обеспечивает тонкий контроль доступа. По умолчанию BaasBox предлагает три роли:

  • administrator — полный, неограниченный доступ.
  • backoffice — предоставляет доступ к контенту, созданному зарегистрированным пользователем.
  • registered — роль для только что зарегистрированных пользователей.

BaasBox позволяет добавлять новые роли, каждая новая роль имеет те же права, что и стандартная роль registered.

Для создания пользователей можно использовать консоль или REST API. Как правило, пользователи создаются программным путем с помощью REST API (например, во время регистрации пользователя приложения).

При добавлении пользователей с помощью консоли администратора можно установить пользовательскую роль. При использовании встроенного REST API, новым пользователям присваивается роль registered.

Чтобы создать нового пользователя с помощью консоли BaasBox, откройте USERS > Users и нажмите кнопку New User.

На экране появится форма, которую нужно заполнить.

Поля Username, Password, Retype Password и Role нужно заполнить обязательно, все остальные поля опциональны.

Создайте пользователя user1. Вы можете установить ему любую роль, но обычно используется роль registered. Указав все необходимые данные, нажмите Save changes.

Инструкции по созданию пользователя с помощью REST API можно найти ниже. А теперь нужно настроить место для хранения контента приложения.

4: Создание коллекции

BaasBox систематизирует контент в коллекции, которые очень похожи на коллекции баз данных NoSQL (например, как в MongoDB). Коллекция состоит из документов одного типа. Пользователи, привыкшие работать в SQL, могут представить коллекцию как таблицу. В таком случае документ — это аналог записи в SQL.

Коллекции может создавать только администратор. Обычно коллекции создаются с помощью консоли, но это можно сделать и в REST API.

В данном разделе показано, как создать роль через консоль.

Все необходимые для этого функции находятся в меню Collections и Documents раздела DATA.

Откройте DATA > Collections. На экране появится список текущих коллекций приложения.

Чтобы создать новую коллекцию, кликните по New Collection. На экране появится форма, в которой нужно указать название коллекции.

Введите имя (например, в руководстве коллекция называется todos) и нажмите Save changes. Теперь пользователи приложения могут получить доступ к новой коллекции и документам в ней с помощью REST API.

Теперь пора ознакомиться с тем, как работает REST API.

5: Использование REST API

Теперь вы умеете работать с консолью BaasBox. Пора научиться выполнять те же задачи через REST API.

REST API может использоваться различными типами приложений (от мобильных до консольных). В приведенных ниже примерах используется curl для имитации запросов. Вы можете адаптировать эти примеры в зависимости от фронтенд платформы.

Создание пользователя

Общий синтаксис команды curl для создания пользователя:

curl http://your_ip_address:9000/user \
-d '{"username" : "username", "password" : "password"}' \
-H Content-type:application/json \
-H X-BAASBOX-APPCODE:baasbox_appcode

В данном примере нужно создать пользователя user2. Выберите надёжный пароль (в примере используется стандартное значение X-BAASBOX-APPCODE — пароль по умолчанию 1234567890). Учитывая все данные, команда будет выглядеть так:

curl http://your_ip_address:9000/user \
-d '{"username" : "user2", "password" : "user2_password"}' \
-H Content-type:application/json \
-H X-BAASBOX-APPCODE:1234567890

Она вернёт:

{"result":"ok","data":{"user":{"name":"user2","status":"ACTIVE","roles":[{"name":"registered","isrole":true}]},"id":"a4353548-501a-4c55-8acd-989590b2393c","visibleByAnonymousUsers":{},"visibleByTheUser":{},"visibleByFriends":{},"visibleByRegisteredUsers":{"_social":{}},"signUpDate":"2016-04-05T13:12:17.452-0400","generated_username":false,"X-BB-SESSION":"992330a3-4e2c-450c-8d83-8eaf2903188b"},"http_code":201}

Отформатированный вывод:

{
"result": "ok",
"data": {
"user": {
"name": "user2",
"status": "ACTIVE",
"roles": [
{
"name": "registered",
"isrole": true
}
]
},
"id": "a4353548-501a-4c55-8acd-989590b2393c",
"visibleByAnonymousUsers": {},
"visibleByTheUser": {},
"visibleByFriends": {},
"visibleByRegisteredUsers": {
"_social": {}
},
"signUpDate": "2016-04-05T13:12:17.452-0400",
"generated_username": false,
"X-BB-SESSION": "992330a3-4e2c-450c-8d83-8eaf2903188b"
},
"http_code": 201
}

Обратите внимание на выделенные значения. BaasBox генерирует уникальный id для каждого пользователя. Этот id позволяет извлекать, изменять и удалять документы данного конкретного пользователя с помощью REST API.

Второе выделенное значение — X-BB-SESSION. Это ID сессии, который нужно использовать в запросах user2.

Примечание: В дальнейшем мы будем ссылаться на это значение с помощью user2_session_id.

Аутентификация пользователя

Теперь вы знаете id сессии пользователя user2. Попробуйте узнать это значение для пользователя user1, который был создан ранее через консоль. Для этого нужно войти как user1 через REST API. Общий синтаксис команды curl выглядит так:

curl http://your_ip_address:9000/login \
-d "username=username" \
-d "password=password" \
-d "appcode=baasbox_appcode"

Теперь подставьте в команду свои данные. В нашем случае имя пользователя — user1, а baasbox_appcode — 1234567890.

curl http://your_ip_address:9000/login \
-d "username=user1" \
-d "password=user1_password" \
-d "appcode=1234567890"

Команда вернёт:

{"result":"ok","data":{"user":{"name":"user1","status":"ACTIVE","roles":[{"name":"registered","isrole":true}]},"id":"84191e4c-2471-48a7-98bb-ecdaf118285c","visibleByAnonymousUsers":{},"visibleByTheUser":{},"visibleByFriends":{},"visibleByRegisteredUsers":{"_social":{}},"signUpDate":"2016-04-05T13:06:35.750-0400","generated_username":false,"X-BB-SESSION":"74400b4b-d16c-45a2-ada3-1cd51cc202bb"},"http_code":200}

Отформатированный вывод выглядит так:

{
"result": "ok",
"data": {
"user": {
"name": "user1",
"status": "ACTIVE",
"roles": [
{
"name": "registered",
"isrole": true
}
]
},
"id": "84191e4c-2471-48a7-98bb-ecdaf118285c",
"visibleByAnonymousUsers": {},
"visibleByTheUser": {},
"visibleByFriends": {},
"visibleByRegisteredUsers": {}
},
"signUpDate": "2016-04-05T13:06:35.750-0400",
"generated_username": false,
"X-BB-SESSION": "74400b4b-d16c-45a2-ada3-1cd51cc202bb"
},
"http_code": 200
}

В выводе ID пользователя user1 выделен красным. Этот ID нужен для создания запросов пользователя user1.

Примечание: В дальнейшем мы будем ссылаться на это значение с помощью user1_session_id.

Создание документа

Теперь попробуйте создать два документа. Один из них будет принадлежать пользователю user1, который был создан через консоль, а второй — пользователю user2, созданному через REST API. Документы будут содержать следующее:

{
"list_name": "Task List Name",
"tasks": [
{
"task": "Task Details",
"done": false
},
{
"task": "Task Details",
"done": false
}
]
}

Как видите, документы будут иметь два параметра: название задачи и список задач.

Общий формат команды:

curl -X POST http://your_ip_address:9000/document/collection_name \
-d 'json_formatted_document' \
-H Content-type:application/json \
-H X-BB-SESSION:session_id

Создайте документ пользователя user1. В данном случае коллекция называется todos, а документ будет содержать такой код:

{
"list_name": "User 1 - List 1",
"tasks": [
{
"task": "User1 List1 task 1",
"done": false
},
{
"task": "User1 List1 task 2",
"done": false
}
]
}

Чтобы связать документ с пользователем user1, используйте ID сессии этого пользователя.

Чтобы создать документ для user1, введите команду:

curl -X POST http://your_ip_address:9000/document/todos \
-d '{"list_name":"User 1 - List 1","tasks":[{"task":"User1 List1 task 1","done":false},{"task":"User1 List1 task 2","done":false}]}' \
-H Content-type:application/json \
-H X-BB-SESSION:user1_session_id

Команда вернёт следующий вывод:

{"result":"ok","data":{"@rid":"#24:1","@version":2,"@class":"todos","list_name":"User 1 - List 1","tasks":[{"task":"User1 List1 task 1","done":false},{"task":"User1 List1 task 2","done":false}],"id":"c83309e7-cbbd-49c8-a76b-9e8fadc72d6f","_creation_date":"2016-04-05T20:34:30.132-0400","_author":"user1"},"http_code":200}

В отформатированном виде:

{
"result": "ok",
"data": {
"@rid": "#24:1",
"@version": 2,
"@class": "todos",
"list_name": "User 1 - List 1",
"tasks": [
{
"task": "User1 List1 task 1",
"done": false
},
{
"task": "User1 List1 task 2",
"done": false
}
],
"id": "c83309e7-cbbd-49c8-a76b-9e8fadc72d6f",
"_creation_date": "2016-04-05T20:34:30.132-0400",
"_author": "user1"
},
"http_code": 200
}

Как и новым пользователям, BaasBox присваивает id каждому новому документу. Запишите id документа для дальнейшей работы.

Примечание: В дальнейшем на этот документ мы будем ссылаться с помощью user1_list1_id.

Теперь попробуйте самостоятельно:

  • Создать еще один документ для user1;
  • Создать два документа для user2.

В результате у вас получится четыре документа в коллекции todos.

Примечание: Руководство будет ссылаться на эти документы с помощью условных ID:

  • user1_list1_id
  • user1_list2_id
  • user2_list1_id
  • user2_list2_id

Извлечение документов

Базовый синтаксис команды для извлечения документа по id:

curl http://your_ip_address:9000/document/collection_name/document_id \
-H X-BB-SESSION:session_id

Чтобы извлечь первый документ пользователя user1, введите:

curl http://your_ip_address:9000/document/todos/user1_list1_id \
-H X-BB-SESSION:user1_session_id

Команда выведет:

{"result":"ok","data":{"@rid":"#24:1","@version":2,"@class":"todos","list_name":"User 1 - List 1","tasks":[{"task":"User1 List1 task 1","done":false},{"task":"User1 List1 task 2","done":false}],"id":"c83309e7-cbbd-49c8-a76b-9e8fadc72d6f","_creation_date":"2016-04-05T20:34:30.132-0400","_author":"user1"},"http_code":200}

Отформатированный результат:

{
"result": "ok",
"data": {
"@rid": "#24:1",
"@version": 2,
"@class": "todos",
"list_name": "User 1 - List 1",
"tasks": [
{
"task": "User1 List1 task 1",
"done": false
},
{
"task": "User1 List1 task 2",
"done": false
}
],
"id": "c83309e7-cbbd-49c8-a76b-9e8fadc72d6f",
"_creation_date": "2016-04-05T20:34:30.132-0400",
"_author": "user1"
},
"http_code": 200
}

Теперь попробуйте извлечь этот же документ, но с учётными данными пользователя user2:

curl -X POST http://your_ip_address:9000/document/todos/user1_list1_id \
-H X-BB-SESSION:user2_session_id

Команда вернёт ошибку:

{"result":"error","message":"c83309e7-cbbd-49c8-a76b-9e8fadc72d6f not found","resource":"/document/todos/c83309e7-cbbd-49c8-a76b-9e8fadc72d6f","method":"GET","request_header":{"Accept":["*/*"],"Host":["localhost:9000"],"User-Agent":["curl/7.35.0"],"X-BB-SESSION":["8f5a2e48-0f42-4478-bd1b-d28699158c4b"]},"API_version":"0.9.5","http_code":404}

Отформатированный вывод:

{
"result": "error",
"message": "c83309e7-cbbd-49c8-a76b-9e8fadc72d6f not found",
"resource": "\/document\/todos\/c83309e7-cbbd-49c8-a76b-9e8fadc72d6f",
"method": "GET",
"request_header": {
"Accept": [
"*\/*"
],
"Host": [
"localhost:9000"
],
"User-Agent": [
"curl\/7.35.0"
],
"X-BB-SESSION": [
"8f5a2e48-0f42-4478-bd1b-d28699158c4b"
]
},
"API_version": "0.9.5",
"http_code": 404
}

Как видите, операция вернула ошибку, поскольку user2 не создавал этого документа и не имеет доступа нему. Попробуйте извлечь документ пользователя user2, указав корректные учётные данные, и команда выведет запрашиваемый документ.

Извлечение всех документов

Общий синтаксис команды:

curl http://your_ip_address:9000/document/collection_name \
-H X-BB-SESSION:session_id

Имейте в виду: эта команда возвращает не все существующие документы, а только те документы, к которым имеет доступ указанный пользователь. Например, попробуйте извлечь документы user1.

curl http://your_ip_address:9000/document/todos \
-H X-BB-SESSION:user1_session_id

Вывод команды:

{"result":"ok","data":[{"@rid":"#24:1","@version":2,"@class":"todos","list_name":"User 1 - List 1","tasks":[{"task":"User1 List1 task 1","done":false},{"task":"User1 List1 task 2","done":false}],"id":"c83309e7-cbbd-49c8-a76b-9e8fadc72d6f","_creation_date":"2016-04-05T20:34:30.132-0400","_author":"user1"},{"@rid":"#24:2","@version":1,"@class":"todos","list_name":"User 1 - List 2","tasks":[{"task":"User1 List2 task 1","done":false},{"task":"User1 List2 task 2","done":false}],"id":"7c99c877-d269-4281-8a22-ef72175085f4","_creation_date":"2016-04-05T20:46:14.338-0400","_author":"user1"}],"http_code":200}

Отформатированный вывод:

{
"result": "ok",
"data": [
{
"@rid": "#24:1",
"@version": 2,
"@class": "todos",
"list_name": "User 1 - List 1",
"tasks": [
{
"task": "User1 List1 task 1",
"done": false
},
{
"task": "User1 List1 task 2",
"done": false
}
],
"id": "c83309e7-cbbd-49c8-a76b-9e8fadc72d6f",
"_creation_date": "2016-04-05T20:34:30.132-0400",
"_author": "user1"
},
{
"@rid": "#24:2",
"@version": 1,
"@class": "todos",
"list_name": "User 1 - List 2",
"tasks": [
{
"task": "User1 List2 task 1",
"done": false
},
{
"task": "User1 List2 task 2",
"done": false
}
],
"id": "7c99c877-d269-4281-8a22-ef72175085f4",
"_creation_date": "2016-04-05T20:46:14.338-0400",
"_author": "user1"
}
],
"http_code": 200
}

Как видите, команда извлекла только те документы, к которым у пользователя user1 есть доступ. Чтобы получить документы пользователя user2, укажите его данные.

Обновление документов

Базовый синтаксис:

curl -X PUT http://your_ip_address:9000/document/collection_name/document_id \
-d 'new_json_formatted_document' \
-H Content-type:application/json \
-H X-BB-SESSION:session_id

При обновлении документов нужно иметь в виду следующее:

  1. Только владелец может изменить содержимое документа.
  2. Операция обновления документа не объединяет старые и новые документы. Она заменяет старый документ новым. Это означает, что если в команде обновления будут пропущены некоторые поля из оригинальной версии документа, эти поля будут потеряны.

Попробуйте обновить содержимое документа с помощью user1_list1_id, заменив его на такой код:

{
"list_name": "User 1 - List 1 Updated",
"tasks": [
{
"task": "New User1 List1 task 1",
"done": false
}
]
}

Команда для обновления документа выглядит так:

curl -X PUT http://your_ip_address:9000/document/todos/user1_list1_id \
-d '{"list_name":"User 1 - List 1 Updated","tasks":[{"task":"New User1 List1 task 1","done":false}]}' \
-H Content-type:application/json \
-H X-BB-SESSION:user1_session_id

Эта команда вернёт:

{"result":"ok","data":{"@rid":"#24:1","@version":4,"@class":"todos","list_name":"User 1 - List 1 Updated","tasks":[{"task":"New User1 List1 task 1","done":false}],"id":"c83309e7-cbbd-49c8-a76b-9e8fadc72d6f","_creation_date":"2016-04-05T20:34:30.132-0400","_author":"user1"},"http_code":200}

Отформатированный результат этой команды:

{
"result": "ok",
"data": {
"@rid": "#24:1",
"@version": 4,
"@class": "todos",
"list_name": "User 1 - List 1 Updated",
"tasks": [
{
"task": "New User1 List1 task 1",
"done": false
}
],
"id": "c83309e7-cbbd-49c8-a76b-9e8fadc72d6f",
"_creation_date": "2016-04-05T20:34:30.132-0400",
"_author": "user1"
},
"http_code": 200
}

Как видите, документ успешно обновлён.

Удаление документов

Общий синтаксис команды curl:

curl -X DELETE http://your_ip_address:9000/document/collection_name/document_id \
-H X-BB-SESSION:session_id

Имейте в виду: удалять документы может только их владелец.

Чтобы удалить документ user1_list1_id, введите:

curl -X DELETE http://your_ip_address:9000/document/todos/user1_list1_id \
-H X-BB-SESSION:user1_session_id

Команда вернёт такой результат:

{"result":"ok","data":"","http_code":200}

Это значит, что документ был успешно удалён. Любые попытки получить доступ к документу с этим id будут возвращать ошибку.

Настройка доступа

Ранее вы увидели, как BaasBox блокирует доступ к документу, если у пользователя нет прав доступа к нему. Однако BaasBox позволяет открывать доступ к одному документу нескольким пользователям. Попробуйте передать доступ на документ user1_list1_id пользователю user2.

Общий формат команды:

curl -X PUT http://your_ip_address:9000/document/collection_name/document_id/access_type/user/username \
-H X-BB-SESSION:session_id

Открыть другим пользователям доступ к документу может только его владелец. Вместо access_type в команде нужно указать одно из следующих значений:

  • read
  • update
  • delete
  • all

Чтобы передать пользователю user2 право на чтение документа user1_list1_id, выполните следующую команду, указав учётные данные пользователя user1:

curl -X PUT http://your_ip_address:9000/document/todos/user1_list1_id/read/user/user2 \
-H X-BB-SESSION:user1_session_id

Команда вернёт:

{"result":"ok","data":"","http_code":200}

Теперь пользователь user2 может читать документ user1_list1_id.

6: Настройка Supervisor

Всегда есть риск, что приложение может прервать работу; причиной этого может стать ошибка приложения, перезагрузка системы, и т.д. Потому рекомендуется заранее настроить перезапуск приложения  в случае его сбоя или отключения.

Для поддержки приложения используйте Supervisor.

Примечание: Больше о Supervisor можно узнать в руководстве «Установка и управление Supervisor на сервере Ubuntu и Debian».

Установите Supervisor:

sudo apt-get install supervisor

Создайте конфигурационный файл Supervisor. В руководстве он называется baasbox.conf и находится в /etc/supervisor/conf.d.

sudo nano /etc/supervisor/conf.d/baasbox.conf

Добавьте в файл такой код:

[program:Baasbox]
directory = /home/8host/baasbox-0.9.5
command = /home/8host/baasbox-0.9.5/start
autostart = true
autorestart = true
startsecs = 5
user = 8host
stdout_logfile = /var/log/supervisor/baasbox.log

Примечание: Укажите своё имя пользователя и версию программы.

Обновите настройки Supervisor:

supervisorctl reread
supervisorctl update

Теперь в случае сбоя приложение будет немедленно перезапущено.

Заключение

Теперь вы знаете, как управлять контентом с помощью BaasBox. Также вы умеете управлять пользователями и документами приложения с помощью консоли и REST API.

Данное руководство знакомит только с базовыми функциями BaasBox. Приложение BaasBox имеет множество функций, которые не вошли в это руководство (как, например, резервное копирование, настройка конечных точек и т.п.).

Tags: , , ,

Добавить комментарий

Ваш e-mail не будет опубликован. Обязательные поля помечены *


*

Можно использовать следующие HTML-теги и атрибуты: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>