Установка Habitica локально

Первым шагом к внесению кода на сайт Habitica habitica.com является создание локальной копии сайта для тестирования ваших изменений. Если вы хотите установить Habitica непосредственно на Linux, MacOS или Windows, то есть отдельные страницы с инструкциями:

Если же вы хотите установить Habitica с помощью Vagrant или Docker (независимо от того, какую операционную систему хоста вы используете), то читайте дальше. Отдельные страницы для них будут созданы в ближайшее время.

Следуйте каждому разделу по порядку, следя за выполнением каждой инструкции, прежде чем двигаться дальше. Если у вас возникают ошибки, всегда останавливайтесь и исправляйте их, прежде чем переходить к следующему шагу.

Также важно прочесть «Руководство для кузнецов» для получения справочной информации о кодировании в Habitica.

Эта страница не имеет отношения к разработке мобильных приложений.

Выберите свою платформу[]

Большинство разделов на этой странице должны соблюдаться независимо от того, какую операционную систему вы используете. Однако, когда вы перейдете в раздел «Инструкции по операционной системе» вы обнаружите, что он содержит следующие подразделы:

Vagrant – для установки Habitica на виртуальную машину Ubuntu с помощью Vagrant, который можно запускать на Windows, MacOS и *nix (рекомендуется для Windows, если вы испытываете проблемы при установке на саму Windows, но не рекомендуется в противном случае)
Docker – для запуска Habitica в Docker контейнере

Вы должны следовать только одному из этих подразделов – в зависимости от того, как вы хотите запускать Habitica локально.

Подготовка к устранению ошибок[]

Установка локально не всегда протекает гладко, но мы будем рады помочь вам! Habitica использует много программного обеспечения, и мы понимаем, что это всё сложно установить до тех пор, пока вы не начнете этим пользоваться. Прежде чем возникнут ошибки, выполните все действия, описанные в этом разделе, чтобы при необходимости вы могли легко обратиться за помощью и мы быстро оценили вашу проблему.

Когда вы устанавливайте Habitica:

Записывайте каждую команду, которую вы вводите и все результаты её выполнения – сохраняйте всё в текстовый(-ые) файл(-ы) на случай, если нам потребуется посмотреть их потом.
Внимательно читайте все получаемые сообщения для поиска ошибок.
- Если вы видите ошибку, не продолжайте до тех пор, пока ошибка не будет устранена, поскольку последующие шаги, вероятно, будут работать неправильно.
- Однако, вы можете не обращать внимания на:
  - сообщения об устаревании (npm WARN deprecated ...)
  - необязательные сообщения о сбоях зависимостей (npm WARN optional Skipping failed optional dependency...)
  - npm WARN notsup Not compatible with your operating system or architecture: fsevents@1.0.12
Если вам придется отклониться от каких-либо инструкций в любом месте на этой странице, запишите, что вы сделали, что отличается и почему. Если вам позже потребуется помощь, очень важно, чтобы люди, помогающие вам знали об этих различиях, в противном случае можно потратить очень много времени впустую.

Если вам нужна помощь в исправлении ошибок, загрузите всю собранную информацию, например, на: GitHub Gist, и затем зарегистрируйте проблему на GitHub и сообщите нам следующее:

какая операционная система установлена на вашем компьютере/ноутбуке
какие методы установки вы используете:
- установка Habitica прямо на компьютер/ноутбук;
- установка Habitica используя инструкции на этой странице для Vagrant или Docker;
- установка Habitica на другую виртуальную машину – укажите на какой операционной системе она работает
любые отклонения от стандартных инструкций
любую другую информацию по инструкциям на этой странице, которую попросили вас записать
ссылки на загруженные файлы
с какой проблемой вы столкнулись

Установка Git[]

Создайте аккаунт на GitHub, если у вас его нет.

Установите git (инструкции по установке можно найти здесь).

Переводы строк на Windows[]

Этот раздел актуален только в том случае, если вы используете Vagrant или Docker на компьютере с Windows.

Операционные системы *nix (Linux и Mac OS X) обрабатывают переводы строк иначе, чем Windows. Системы *nix используют символ перевода строки (англ. line feed, LF) \n, в то время как Windows использует комбинацию из возврата каретки (англ. carriage return, CR) и перевода строки, \r\n (CRLF). Поскольку разработчики Habitica используют разные операционные системы, чтобы обеспечить максимальную совместимость, необходимо настроить Git в Windows, чтобы гарантировать, что в репозиторий коммитится только символ перевода строки (LF).

Windows Git Setup — Окно «Configuring the line ending conversions»

То, как вы это настроите, зависит от того, будете ли вы выполнять всю работу по разработке Habitica непосредственно в Windows, или вы будете устанавливать виртуальную машину Unix Vagrant на свой компьютер с Windows и использовать машину Vagrant для всей разработки. Соответствующую настройку можно выбрать при установке Git (см. скриншот, но прежде чем выбрать опцию, прочитайте текст дальше) или впоследствии, используя простой инструмент командной строки.

Если вы будете выполнять редактирование всего кода в машине Vagrant или в контейнере Docker, то при появлении окна «Configuring the line ending conversions», выберите Checkout as-is, commit Unix-style line endings. Или настройте этот параметр из командной строки, выполнив:
git config --global core.autocrlf input

Если вы будете редактировать код прямо на хост-компьютере Windows (т. е. вы используете машину Vagrant или контейнер Docker, чтобы просто запустить сервер Habitica и протестировать его), то выберите Checkout Windows-style, commit Unix-style line endings, или настройте этот параметр, выполнив
git config --global core.autocrlf true

Если вы выберете один параметр сейчас, а потом решите изменить способ разработки, вы можете выполнить соответствующую команду git config --global core.autocrlf ... для изменения этой настройки.

Для получения дополнительной информации об переводах строк и пробелах в Git, см. раздел «Форматирование и пробелы» в книге Pro Git.

Если вы не хотите устанавливать параметр core.autocrlf глобально, см. Работа с переводами строки > Per-repository settings, чтобы узнать как устанавливать его только для отдельных репозиториев. Это будет иметь отношение только к вам, если вы уже используете Git для других проектов или будете использовать его для других в будущем.

Форк и клонирование репозитория Habitica[]

Получите копию кодовой базы Habitica. Это можно сделать несколькими способами; ниже приведен простейший способ, основанный на статье Fork A Repo с GitHub.

Форкните репозиторий Habitica перейдя по https://github.com/HabitRPG/habitica и нажав на кнопку "Fork". Это создаст копию репозитория Habitica на вашем аккаунте GitHub.
На вашем компьютере откройте командную строку или окно терминала. Перейдите в каталог, в который вы хотите скопировать кодовую базу Habitica.
Склонируйте свою копию репозитория Habitica с помощью команды ниже (замените ВашеИмяПользователя на ваше имя пользователя GitHub). Это скопирует код Habitica на ваш компьютер, поместив репозиторий в новый каталог «habitica» в ваш текущий каталог.
git clone https://github.com/ВашеИмяПользователя/habitica.git
Откройте только что созданный каталог "habitica":
cd habitica
Оставайтесь в этом каталоге для всех дальнейших действий на этой странице, если не указано иное.
Настройте Git для синхронизации вашего форка с репозиторием Habitica.
git remote add upstream https://github.com/HabitRPG/habitica.git
Убедитесь, что все настроено правильно, выполнив команду git remote -v, которая должна будет выдать то же, что и ниже, но с вашим именем пользователя GitHub:

  origin   https://github.com/ВашеИмяПользователя/habitica.git (fetch)
  origin   https://github.com/ВашеИмяПользователя/habitica.git (push)
  upstream https://github.com/HabitRPG/habitica.git (fetch)
  upstream https://github.com/HabitRPG/habitica.git (push)

После того, как вы склонируйте репозиторий Habitica, у вас будет стоять ветка develop по умолчанию. Это правильная ветка для установки Habitica локально. Вам не нужно переходить на другие ветки, но если вы по какой-либо причине это сделали, вы можете вернуться на ветку "develop", выполнив git checkout develop, прежде чем продолжить установку. Чтобы узнать на какой ветке вы находитесь, выполните git branch (ветка отмеченная звёздочкой перед её названием и будет текущей).

Начальная настройка Habitica[]

Примечание для Windows: Все команды cp на этой странице должны быть заменены на copy.

Создайте файл конфигурации config.json скопировав (не переименовывая) пример:
cp config.json.example config.json
Как правило, вам не нужно редактировать config.json, но если вам известна какая-либо причина, вы можете сделать это сейчас. Его можно отредактировать в любой момент при необходимости.
Нет причин изменять значение для ADMIN_EMAIL. Это устаревшая константа и, вероятно, скоро будет удалена.

Инструкции по операционной системе[]

Этот раздел содержит следующие подразделы, и вам нужно следовать только одному из них (игнорируя остальные):

Vagrant
Docker

Vagrant[]

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

Вы можете использовать Vagrant на разных системах, включая Windows, Mac OS X и Linux. Точно известно, что эти инструкции хорошо работают в системах Unix (Linux и Mac OS X), а пользователи Windows могут иногда столкнуться с ошибками. Если у вас нет возможности использовать среду Unix вместо этого и вы столкнулись с проблемами при настройке, то напишите о проблеме на Github.

Установите последнюю версию VirtualBox (бесплатный инструмент для виртуалиазции).
Установите последнюю версию Vagrant. Процесс установки описанный ниже автоматически fetch a Vagrant box из vagrantcloud.com; если вы получили сообщение об ошибке:
The box 'thepeopleseason/habitrpg' could not be found, то у вас не последняя версия Vagrant и вам нужно обновить его.
Примечание: Если вы получили сообщение об ошибке:
The requested address is not valid in its context. - connect(2) for "0.0.0.0" port 3000 (Errno::EADDRNOTAVAIL), это может быть связано с багом в Vagrant версии 1.9.3, который будет исправлен в следующем релизе. Временное решение: использовать Vagrant версии 1.9.2.
Если вы работаете на Windows, откройте командную строку с правами администратора. Для других операционных систем, откройте окно терминала.
Скопируйте Vagrantfile из примера:
cp Vagrantfile.example Vagrantfile
По желанию, увеличить объем памяти и количество CPU, выделенных для box, открыв Vagrantfile и изменив значения v.memory и v.cpus. При первом выполнении vagrant up выполняются скрипты для предоставления виртуальной машине пакетов программного обеспечения, необходимых для habitica. Если что-то из этого завершится с ошибкой, связанной с памятью или CPU, то выполните vagrant destroy, и затем начните настройку Vagrant со следующего шага. However memory and cpus can be changed after the first vagrant up has been successful by simply modifying the values and running vagrant reload (Это полезно, если надо выделить больше памяти и CPU для начальной настройки, а затем уменьшить их для ежедневного пользования). Вы возможно захотите увеличить v.memory, чтобы избежать создания файлов подкачки, или уменьшить его, если ваш компьютер не имеет достаточно памяти под box. Однако следует помнить, что недостаточное выделение памяти может привести к ошибкам.
Загрузите Vagrant box (в первый раз это может занять 30-60 минут):
vagrant up
- Если "vagrant up" успешно загружает virtual box, но не может его запустить, то перезагрузите вашу систему, проверьте настройки BIOS, и убедитесь, что аппаратная виртуализация включена.
- Если "vagrant up" завершится успешно, он сообщит:
  'vagrant up' is finished. Continue with the instructions at http://habitica.wikia.com/wiki/Setting_up_Habitica_Locally"
Авторизируйтесь в среде (виртуальная машина Ubuntu Linux):
vagrant ssh
- Прежде чем эта команда сработает, ваша переменная PATH должна включать программу ssh. Она уже будет установлена для пользователей Unix, Linux и Mac OS. Для пользователей Windows, скорее всего, у вас есть ssh в каталоге Git, и если его еще нет в переменной PATH, вы можете добавить его с помощью::
  set PATH=%PATH%;C:\Program Files (x86)\Git\bin
Убедитесь, что команда ssh выполнилась успешно, и вы сейчас находитесь в vagrant компьютере. Если это не так, не переходите дальше, пока вы не подключитесь по ssh к vagrant компьютеру. Если ssh был успешен, приглашение командной строки vagrant будет таким vagrant@habitrpg:/vagrant$.
Убедитесь, что у вас установлены правильные версии NodeJS и npm:
node --version; npm --version
Важно: Вы должны установить node 10 и npm 6. У вас могут появиться ошибки, если вы будете использовать другие версии. Если вам нужно использовать разные версии на вашем компьютере для работы, не связанной с Habitica, вы можете использовать nvm для управления версиями.
- В противном случае, напишите нам на GitHub, чтобы мы могли исправить скрипт установки vagrant. Если вы не уверены те ли версии у вас установлены, вы можете посоветоваться там же.
Установите требуемые модули для node (это может занять несколько минут):
npm install
- При возникновении ошибок, выполните npm install ещё раз.
- В системе Windows вам может потребоваться выполнить эту команду с повышенными правами доступа, и указать npm устанавливать без создания символьных ссылок, для избежания ошибок: sudo npm install --no-bin-links. Вы также можете установить bcrypt вручную: sudo npm install bcrypt.
- Если вы всё ещё видите ошибки после второго выполнения, сообщите о проблеме на GitHub. Укажите, что вы выполняли её дважды. Мы дадим вам совет по выполнению каждой части npm install индивидуально (если вам удобно, вы можете делать это сами, но также держите нас в курсе, чтобы мы могли отследить возникновение этой проблемы).
Выполните эти команды:
- gulp build
Следуйте инструкциям раздела «Запуск Habitica» ниже.

Примечание: При создании среды Vagrant, параметр конфигурации автоматически изменяет рабочую директорию на /vagrant (место расположения исходников Habitica) при входе в систему. Если вы не хотите, чтобы так происходило, отредактируйте файл /home/vagrant/.bashrc и удалите строку cd /vagrant.

Примечание: При создании среды Vagrant, параметр конфигурации автоматически переменную среды DISPLAY в :99 в файле /home/vagrant/.bashrc. Это нужно для запуска сквозного (e2e) набора тестов. Если вы не используете bash, то вы можете вручную экспортировать эту переменную перед запуском тестов: export DISPLAY=:99

Примечание: Вы можете выбрать, чтобы начальная команда "vagrant up" запускала всю систему (напр., для выполнения npm start). Если вы решите сделать это, отредактируйте файл vagrant_scripts/vagrant.sh в вашем каталоге habitica, и удалите символ "#" перед строкой autostart_habitrpg. После того, как система запустилась, вам нужно будет открыть другое окно командной строки, чтобы выполнить "vagrant ssh", и вы не сможете интерактивно перезагрузить сервер. Из-за этих недостатков вы должны запускать сервер автоматически только, если вы знаете, что делаете.

Docker[]

Docker allows development in containers requiring little setup and ensuring a consistent environment for all developers. It also means that you do not need to clutter your host machine with dependencies.

Получение помощи по этим инструкциям[]

The instructions in this Docker section might be outdated or incorrect in parts. If you need help, post to the Aspiring Blacksmiths guild.

If you are familiar with Docker, your assistance in improving these instructions would be most welcome! Here are some points of confusion that contributors have identified:

Not entirely clear the difference between the steps: "Use docker-compose to build and start...", "Bootstrap your local clone using...". Are they dependent of each other? Can one step be followed instead of the other? If one step is an optional step, a label that states "optional" may be very helpful. If one step must be followed after the conclusion of another step, then statements like "Go to ----" at the end of the step may be helpful.
Running the command `docker-compose exec web sh` produced error `ERROR: No such service: web`. This has been reproduced by another member of our group who has successfully installed npm while I failed (not sure if that factor is connected to the issue but thought it may be useful to mention).

Начальная настройка Docker[]

Before beginning, follow the instructions for installing docker and docker-compose: https://docs.docker.com/compose/install/ .

Verify your installation by clicking the Docker Quickstart Terminal icon on your Desktop (Windows) or Launchpad (Mac OS X).

Follow all the directions in this page before the "Instructions by Operating System" section.

In the Docker Quickstart Terminal, cd to your local habitica folder.

Используйте docker-compose для сборки и запуска базы данных mongo и приложения habitica[]

The docker-compose.yml file will build a habitica container using the Dockerfile build file and pull the latest mongo image:
docker-compose up -d This will start three containers in the background.

$ docker ps
 CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS              PORTS                              NAMES
 cf95c4331acf        habitica_client     "npm run client:dev"     25 hours ago        Up 5 seconds        3000/tcp, 0.0.0.0:8080->8080/tcp   habitica_client_1
 f9bda8e04e9e        habitica_server     "npm start"              25 hours ago        Up 6 seconds        0.0.0.0:3000->3000/tcp             habitica_server_1
 17edaab645a4        mongo               "docker-entrypoint.s…"   2 days ago          Up 7 seconds        0.0.0.0:27017->27017/tcp           habitica_mongo_1

Habitica is available on port 3000 and mongo is on port 27017. The version of Habitica running in habitica_client is branch:develop of the Habitica repository.

Note: The application files are stored in an ephemeral container so changes can be easily lost. It is safer and more convenient to mount your local clone of the Habitica repository in the container.

Загрузите вашу локальную копию используя инструменты уже установленные в контейнере[]

Use docker-compose again to stop these containers:
docker-compose stop
Then mount your local clone directory to the habitica_client container and bootstrap:
docker run -t --volume `pwd`:/usr/src/habitrpg habitica_client npm install
Run the containers using the local clone:
docker-compose -f docker-compose.yml -f docker-compose.dev.yml up -d

Now changes made to the local clone will be served via the container.

Note: The above step will create another container in your machine.

$ docker ps
 CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS              PORTS                              NAMES
 a687e85ac965        habitica_client     "npm run client:dev"     10 minutes ago      Up 5 seconds        3000/tcp, 0.0.0.0:8080->8080/tcp   habitica_client_1
 cf95c4331acf        habitica_client     "npm run client:dev"     25 hours ago        Up 5 seconds        3000/tcp, 0.0.0.0:8080->8080/tcp   habitica_client_1
 f9bda8e04e9e        habitica_server     "npm start"              25 hours ago        Up 6 seconds        0.0.0.0:3000->3000/tcp             habitica_server_1
 17edaab645a4        mongo               "docker-entrypoint.s…"   2 days ago          Up 7 seconds        0.0.0.0:27017->27017/tcp           habitica_mongo_1

This extra container will have random name like elastic_keller and can be removed with docker rm [container_name].

If you experience any errors when running npm commands, check that the correct versions of NodeJS and npm have been installed:
node --version; nodejs --version
Важно: Вы должны установить node 10 и npm 6. У вас могут появиться ошибки, если вы будете использовать другие версии. Если вам нужно использовать разные версии на вашем компьютере для работы, не связанной с Habitica, вы можете использовать nvm для управления версиями.
If incorrect versions have been installed, please report it by logging an issue in GitHub so that we can fix the docker configuration. If you are not sure how to install the correct versions, you can ask for help there.

It is important that version 3.4 of MongoDB is used (later versions will give you errors because they don't have the $pushall operator, which is used by Habitica's dependencies). After Pull Request #10270 has been merged, the correct version will be used automatically but until then you must manually ensure that version 3.4 is used. If you need help, ask in the Aspiring Blacksmiths guild.

Запуск тестов в docker контейнерах[]

Once you've started the two docker containers with docker-compose, you can attach to the habitrpg_client container for test execution.

$ docker-compose exec client sh
# <--here's your bash

Now you are in the container, and you can execute test suites using the test commands given in Using Your Local Install to Modify Habitica's Website and API.

While creating unit tests, you may also want to run a docker container that only runs tests.

$ docker run --name habitica_test -it --volume `pwd`:/usr/src/habitrpg habitica_client gulp test:${your_test_category}:watch

The command above creates a container called habitica_test, which you can stop and start for running tests.

Используйте существующий экземпляр mongodb вместо контейнера mongo[]

If you want to avoid the mongodb docker container and instead run Habitica against an existing mongodb instance, launch the habitica_web container with an override to the NODE_DB_URI environment variable:
docker run --env NODE_DB_URI=mongodb://your/database habitica_web, or
docker run --env NODE_DB_URI=mongodb://your_hostname/habitrpg habitica_web

It is important that version 3.4 of MongoDB is used (later versions will give you errors because they don't have the $pushall operator, which is used by Habitica's dependencies).

Запуск Habitica[]

Убедитесь, что сервер базы данных MongoDB работает. Так и должно быть, если вы только что выполнили вышеуказанные шаги, но если вы возвращаетесь к локальной копии после перерыва, его возможно придется перезапустить; обратитесь к интерактивным инструкциям MongoDB для вашей операционной системы или задайте вопрос в гильдии Aspiring Blacksmiths (Habitica Coders), если вам нужна помощь.
Убедитесь, что время на вашем компьютере или виртуальной машине установлено с точностью до секунды, в противном случае вы увидите ошибки «RequestTimeTooSkewed».
Убедитесь, что вы скопировали содержимое config.json.example в config.json, как отмечалось ранее в верхней части этой странице.
В одной командной строке или терминале выполните сборку клиента сайта с помощью npm run client:dev. Он автоматически будет пересобираться при сохранении изменений в клиентских файлах, а также сообщать вам о любых ошибках.
В другой командной строке или терминале скомпилируйте различные файлы и запустите веб-сервер Habitica выполнив npm start, и посмотрите вывод обеих этих команд.
- If you see an error like [nodemon] Internal watch failed: watch /any/path/to/a/file ENOSPC, edit the .nodemonignore file to add website/raw_sprites/** as the final line. You'll find that file in the top level habitica directory (i.e., in the same directory as the config.json file). On Linux, if that does not fix it, execute this command:
  echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p
  After implementing either of those fixes, run npm start again.
- Если вы видите какие-либо другие ошибки или предупреждающие сообщения, то прежде, чем двигаться дальше, устраните их самостоятельно или сообщите о них, следуя указаниям в разделе «Подготовка к устранению ошибок» в верхней части этой страницы. Обратите внимание, что даже если вывод закончился сообщением Done, without errors, над ним все еще могут быть ошибки, которые необходимо устранить, как на этом скриншоте. Возможно, что ошибки прекратятся, если вы нажмете Ctrl-C и снова выполните npm start.
- Выполнение npm start закончится, когда вы увидите что-то похожее на строку info: Connected with Mongoose без ошибок после нее.
Откройте в браузере http://localhost:8080 для тестирования приложения.
- Note that another port, 3000 by default, is used by Express. That port can be configured using the PORT variable in config.json.
- For Vagrant installations, if port 3000 was already in use by any service on your machine, Vagrant will have automatically selected another port between 3000 and 3050, and will have listed that port in its own output.
- The output of npm start will confirm the port in use: info: Express server listening on port 3000. If you do not see that message, then npm start has not run correctly.
Если вы попали на главную страницу сайта, но загрузка не заканчивается или вы находитесь в окне авторизации, но кнопка входа ничего не делает, почистите локальное хранилище (local storage) для «localhost». Для этого откройте http://localhost:8080/static/clear-browser-data и нажмите на красную кнопку «Clear Data» или используя консоль разработчика в вашем браузере (погуглите как очистить локальное хранилище в вашем браузере). Затем перезагрузите главную страницу.
Создайте один или несколько аккаунтов для тестирования. База данных, с которой работает ваша локальная копия находится на вашем компьютере; это не та база данных, которая используется самой Habitica, поэтому ваша обычная учетная запись Habitica будет вам недоступна.

Что дальше: Использование вашей локальной копии[]

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

Также посмотрите «Руководство для кузнецов», в котором содержится информация об используемых технологиях, структуре кода Habitica, идеях о том, как вы можете помочь, и другая информация.