Updated the readme to be more helpful
This commit is contained in:
parent
50c29233ae
commit
741bcc368c
153
README.md
153
README.md
|
@ -1,10 +1,10 @@
|
||||||
# Biblical Resources for Translators API
|
# Biblical Resources for Translators API
|
||||||
|
|
||||||
## Laravel
|
## Laravel
|
||||||
The API is build in [Laravel](https://laravel.com/docs/7.x), a PHP framework. To get the backend up and running locally
|
The API is built in [Laravel](https://laravel.com/docs/7.x), a PHP framework. To get the backend up and running locally
|
||||||
[Laravel Homestead](https://laravel.com/docs/7.x/homestead) is the recommended approach. Laravel is currently on version 8,
|
[Laravel Homestead](https://laravel.com/docs/7.x/homestead) is the recommended approach. Laravel is currently on version 8,
|
||||||
but our system is using the version 7.x series. Just make sure you grab the correct version to avoid any possible snags that
|
but our system is using the version 7.x series. Just make sure you grab the correct version to avoid any possible snags that
|
||||||
could show up across major version.
|
could show up across major versions.
|
||||||
|
|
||||||
Homestead uses [Vagrant](https://www.vagrantup.com) which is a virtual machine tool to make building and maintaining
|
Homestead uses [Vagrant](https://www.vagrantup.com) which is a virtual machine tool to make building and maintaining
|
||||||
VMs easier. By using a VM to host the API server, we can avoid potential conflicts with the local development environment
|
VMs easier. By using a VM to host the API server, we can avoid potential conflicts with the local development environment
|
||||||
|
@ -15,3 +15,152 @@ If Homestead is not an option, you may follow the installation directions in the
|
||||||
Laravel directly on your local machine and run `php artisan serve`. You will need to alter the Frontend's environment
|
Laravel directly on your local machine and run `php artisan serve`. You will need to alter the Frontend's environment
|
||||||
configuration to point to the correct server.
|
configuration to point to the correct server.
|
||||||
|
|
||||||
|
## Config Homestead Project
|
||||||
|
Once Laravel Homestead is installed and working, you will need to setup a project in the Homestead.yaml file. This process
|
||||||
|
requires that you determine a local hostname to use for the API server and a suitable location for the code. A typical setup
|
||||||
|
would use `brt.api` or `brt.local` as the hostname. The folder/directory can be anywhere your user account has read/write permisisons
|
||||||
|
but typically will be something like `~/Code/brt`. With these values in mind, you would edit your Homestead.yaml file
|
||||||
|
and add the following:
|
||||||
|
|
||||||
|
```
|
||||||
|
folders:
|
||||||
|
- map: ~/Code/brt/
|
||||||
|
to: /home/vagrant/brt
|
||||||
|
|
||||||
|
sites:
|
||||||
|
- map: brt.api
|
||||||
|
to: /home/vagrant/Code/gwt/public
|
||||||
|
php: "7.2"
|
||||||
|
|
||||||
|
databases:
|
||||||
|
- brt
|
||||||
|
```
|
||||||
|
|
||||||
|
A complete Homestead.yaml file might look like the following (keep in mind that if you use Homestead for other projects your
|
||||||
|
Homestead.yaml file will look very different, but then you would probably already know that and not need this document ;-) )
|
||||||
|
|
||||||
|
```
|
||||||
|
---
|
||||||
|
ip: "192.168.1.80"
|
||||||
|
memory: 2048
|
||||||
|
cpus: 2
|
||||||
|
provider: virtualbox
|
||||||
|
|
||||||
|
authorize: ~/.ssh/id_rsa_key.pub
|
||||||
|
|
||||||
|
keys:
|
||||||
|
- ~/.ssh/id_rsa_key
|
||||||
|
|
||||||
|
folders:
|
||||||
|
- map: ~/Code/brt/
|
||||||
|
to: /home/vagrant/code
|
||||||
|
|
||||||
|
sites:
|
||||||
|
- map: brt.api
|
||||||
|
to: /home/vagrant/Code/gwt/public
|
||||||
|
php: "7.2"
|
||||||
|
|
||||||
|
databases:
|
||||||
|
- brt
|
||||||
|
|
||||||
|
variables:
|
||||||
|
- key: APP_ENV
|
||||||
|
value: local
|
||||||
|
|
||||||
|
ports:
|
||||||
|
- send: 9912
|
||||||
|
to: 9912
|
||||||
|
```
|
||||||
|
|
||||||
|
The *folders* block configures a fileshare connection between the vagrant box and your local filesystem. The *map*
|
||||||
|
variable is the location of your project code from the perspective of your host machine. It is where you will point your code
|
||||||
|
editor while you work on the project. The *to* variable is where the virtual machine (VM) looks for that same code. It is not
|
||||||
|
aware of the filesystem layout of your host machine, so it needs to know how to find your code from within its own environment.
|
||||||
|
Think of it as a roadmap where the street names are different depending on whether you are a local or a guest.
|
||||||
|
|
||||||
|
The *sites* block works similarly, only now we are telling Vagrant how to configure the web server that will serve up our API.
|
||||||
|
*map* is the hostname we will use in the browser (though in our case we are not accessing the backend API via a browser. Try it,
|
||||||
|
you won't get very far. This is because the actual frontend (FE) for the site lives in a different [repo](https://content.bibletranslationtools.org/WycliffeAssociates/en_btr_frontend)).
|
||||||
|
*to* refers to the place where the web server will need to find the startup code for the site. Note that it is not exactly the
|
||||||
|
same as what we have set in the *folders* block. This is important because the `public` subfolder of a Laravel project contains
|
||||||
|
an `index.php` file which is what 'boots' the system whenever the API is accessed by the web server.
|
||||||
|
|
||||||
|
If you are unsure where your Homestead.yaml file is or need help configuring additional options re-visit the section above.
|
||||||
|
|
||||||
|
## Backend Code (This Repo)
|
||||||
|
Once your VM is configured, you need to clone this repo (en_btr_backend) into your local working directory so that your VM can read the code.
|
||||||
|
Do this by running the following command within a terminal window within your local working directory:
|
||||||
|
|
||||||
|
```
|
||||||
|
git clone https://content.bibletranslationtools.org/WycliffeAssociates/en_btr_backend.git .
|
||||||
|
```
|
||||||
|
|
||||||
|
Not the space + period at the command. Don't leave it out. Otherwise, git will create a new folder named `en_btr_backend`
|
||||||
|
and you will need to update your Homestead.yaml file or delete the new folder and try again. Either approach is fine, just don't
|
||||||
|
be fooled by git's strong opinions.
|
||||||
|
|
||||||
|
Once you have cloned the backend code, go ahead and try running `vagrant up` in your ~/Homestead folder. If your Homestead.yaml configs are in good order
|
||||||
|
Vagrant should take off and start dumping a lot of information to your terminal screen. Don't worry about it unless (or until) Vagrant
|
||||||
|
complains with an error. If you hit an error, revisit the above steps and verify your configuration. If you still have issues and you
|
||||||
|
cannot get past the `vagrant up` process, you will need some extra assistance. Let us know, and we will do our best to help you.
|
||||||
|
|
||||||
|
## Build the database
|
||||||
|
Assuming that Vagrant succeeded, you now have fully functional VM ready to run the API on your computer. That's great! But you still
|
||||||
|
need some data or the API is useless. The source data for the project lives in various repos at WA's git server, but you don't need to
|
||||||
|
worry about that. For testing purposes, there are some files provided in this repo under the `test_files` folder. You will need to move
|
||||||
|
them to the `storage` folder so that the Laravel app can find them and use them to build the DB. Run the following
|
||||||
|
command from within your local working directory:
|
||||||
|
|
||||||
|
```
|
||||||
|
cp -fr test_files/* storage/
|
||||||
|
```
|
||||||
|
|
||||||
|
Now the files we need are located within the `storage` folder which is where they will ultimately be housed on the live API server.
|
||||||
|
With the test files in place, you are almost ready to build the database. However, before you can build the database, you need to
|
||||||
|
make sure that your Laravel config knows how to access the database. Open up the `.env` file in your editor (the `.env` file is in
|
||||||
|
the root of the project folder). Make sure these settings are somehwere in that file:
|
||||||
|
|
||||||
|
```
|
||||||
|
DB_CONNECTION=mysql
|
||||||
|
DB_HOST=127.0.0.1
|
||||||
|
DB_PORT=3306
|
||||||
|
DB_DATABASE=gwt
|
||||||
|
DB_USERNAME=homestead
|
||||||
|
DB_PASSWORD=secret
|
||||||
|
```
|
||||||
|
|
||||||
|
Now (as in right now, don't wait!), run the following command:
|
||||||
|
|
||||||
|
```
|
||||||
|
php artisan gwt:import-lexical-entries
|
||||||
|
```
|
||||||
|
|
||||||
|
and
|
||||||
|
|
||||||
|
```
|
||||||
|
php artisan gwt:import-ulb-xml
|
||||||
|
```
|
||||||
|
|
||||||
|
These two commands don't give you much output unless something breaks. When they are completed, your
|
||||||
|
database will have the data to run the API server on your local machine.
|
||||||
|
|
||||||
|
## THAT'S A WRAP!
|
||||||
|
At this point, there is not much else you can do with the API. It serves up the files needed by the
|
||||||
|
frontend so that the frontend can build the site in a browser. If you want to prove that the API exists
|
||||||
|
and works, you can run the following command in your terminal:
|
||||||
|
|
||||||
|
```
|
||||||
|
curl http://gwt.api/api/v1/books
|
||||||
|
```
|
||||||
|
|
||||||
|
You should get something back that looks like
|
||||||
|
|
||||||
|
```
|
||||||
|
{"data":[{"type":"books","id":"colossians","attributes":{"name":"Colossians","created-at":"2020-10-07T15:28:35+00:00","updated-at":"2020-10-07T15:28:35+00:00"},"relationships":{"chapters":{"links":{"self":"http:\/\/gwt.api\/api\/v1\/books\/colossians\/relationships\/chapters","related":"http:\/\/gwt.api\/api\/v1\/books\/colossians\/chapters"}}},"links":{"self":"http:\/\/gwt.api\/api\/v1\/books\/colossians"}},{"type":"books","id":"philippians","attributes":{"name":"Philippians","created-at":"2020-10-07T15:28:07+00:00","updated-at":"2020-10-07T15:28:07+00:00"},"relationships":{"chapters":{"links":{"self":"http:\/\/gwt.api\/api\/v1\/books\/philippians\/relationships\/chapters","related":"http:\/\/gwt.api\/api\/v1\/books\/philippians\/chapters"}}},"links":{"self":"http:\/\/gwt.api\/api\/v1\/books\/philippians"}}]}
|
||||||
|
```
|
||||||
|
|
||||||
|
Yes, it looks like "YUCK! I can't do anything with that." But don't worry. The frontend loves this stuff and will have no trouble eating it up,
|
||||||
|
I mean, consuming it ;-).
|
||||||
|
|
||||||
|
To get the frontened up and running,
|
||||||
|
head on over to [https://content.bibletranslationtools.org/WycliffeAssociates/en_btr_frontend](https://content.bibletranslationtools.org/WycliffeAssociates/en_btr_frontend)
|
||||||
|
|
Loading…
Reference in New Issue