See in Reader
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
|
||||
|
||||
## 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,
|
||||
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
|
||||
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
|
||||
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