-
Notifications
You must be signed in to change notification settings - Fork 3
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #82 from CoralineAda/readme-clone-repo
Continue developing README
- Loading branch information
Showing
1 changed file
with
70 additions
and
48 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -10,60 +10,80 @@ TMI-Web has three primary components: the web application, the survey response d | |
|
|
||
|  | ||
|
|
||
| Survey data is exported from your survey platform as a comma-separated-value (CSV) file, then imported into TMI-Web using the browser interface. TMI-Web stores the survey response data in a relational database, and creates personas in a graph database as the survey data is analyzed. | ||
| Survey data is exported from your survey platform as a comma-separated-value (CSV) file, then imported into TMI-Web using the browser interface. TMI-Web stores the survey response data in a relational database, and creates personas in a graph database as the survey data is analyzed. | ||
|
|
||
| (To make sure that the web application is always responsive, certain long-running operations are carried out in the background, requiring a key-value store database that's used for a background job queue.) | ||
|
|
||
| ## Setting up your local development environment | ||
|
|
||
| Instructions for installing and running TMI-Web locally are provided below. | ||
|
|
||
|
|
||
| ### Get to your command line | ||
|
|
||
| Depending on the operating system you use, there may be different ways for you to access your local command line. Understanding how to navigate the file system and run programs from the command line is essential, so you're encouraged to find tutorials if you need help getting started. | ||
|
|
||
| ### Clone this repository | ||
|
|
||
| In your terminal, navigate to the folder you use to store your other code projects. Or, you can navigate to any convenient location in your home directory. | ||
|
|
||
| Make a local copy of this repository by typing: | ||
|
|
||
| git clone [email protected]:CoralineAda/tmi-web.git | ||
|
|
||
| Navigate to the `tmi-web` directory with: | ||
|
|
||
| cd tmi-web/ | ||
|
|
||
| The rest of the instructions below assume that you are in the root `tmi-web` directory. | ||
|
|
||
| ### Install Ruby | ||
|
|
||
| TMI-Web requires Ruby version 3.2.2 or higher. To check what version of Ruby your computer has installed, go to your terminal and type | ||
| TMI-Web requires Ruby version 3.2.2 or higher. To check what version of Ruby your computer has installed, type: | ||
|
|
||
| ruby -v | ||
|
|
||
| Upgrade your Ruby version as needed using the package manager of your choice. If you need help, refer to the Ruby installation guide at https://www.ruby-lang.org/en/documentation/installation/ | ||
| Upgrade your Ruby version as needed using the package manager of your choice. If you need help, refer to the Ruby installation guide at [https://www.ruby-lang.org/en/documentation/installation/](https://www.ruby-lang.org/en/documentation/installation/) | ||
|
|
||
| ### Install PostgreSQL | ||
|
|
||
| TMI-Web uses two databases, the first of which is the relational database PostgreSQL. (This is the database that survey responses are stored in.) | ||
| The first database to set up is the relational database, PostgreSQL. (This is the database that survey responses are stored in.) | ||
|
|
||
| You will need to install and run postgres using the instructions at https://www.postgresql.org/download/ | ||
| You can install and run PostgreSQL using the instructions at [https://www.postgresql.org/download/](https://www.postgresql.org/download/) | ||
|
|
||
| ### Install Neo4j | ||
|
|
||
| The other database that TMI-Web uses is the graph database Neo4j. (This is where TMI-Graph data is stored, including interactive personas and identity and experience codes.) | ||
| The next database to set up is the graph database, Neo4j. (This is where interactive personas and identity and experience codes are stored.) | ||
|
|
||
| You can install Neo4j from https://neo4j.com/product/neo4j-graph-database/ | ||
| You can install Neo4j from [https://neo4j.com/product/neo4j-graph-database/](https://redis.io/docs/latest/operate/oss_and_stack/install/install-redis/) | ||
|
|
||
| Once installed, you will need to start Neo4j, most easily using the native application. Use the application to create an empty database called `tmi_graph`. You will need to manually start the database from the application each time prior to starting the Rails application. | ||
| Once installed, open the Neo4j native application and use the interface to create an empty database called `tmi_graph`. You will need to keep the Neo4j application open and the `tmi_graph` database started while running the Rails application locally. | ||
|
|
||
| ### Install Redis | ||
|
|
||
| Use the package manager of your choice to install and run Redis. (Redis is used by TMI-Web as a queue for background jobs.) You can find instructions at https://redis.io/docs/latest/operate/oss_and_stack/install/install-redis/ | ||
| The final database to install is Redis. (Redis is used by TMI-Web as a queue for background jobs.) You can find instructions at [https://redis.io/docs/latest/operate/oss_and_stack/install/install-redis/](https://redis.io/docs/latest/operate/oss_and_stack/install/install-redis/) | ||
|
|
||
| ### Install the Rails application | ||
|
|
||
| TMI-Web uses Ruby on Rails as a web application framework. It also uses a number of specialized Ruby libraries called gems. To install everything that the web application needs, navigate in your terminal to the tmi-web directory that you cloned from Github. Then type | ||
| TMI-Web is built on the Ruby on Rails web application framework. It also uses a number of specialized Ruby libraries called gems. To install everything that the web application needs, make sure that you're in the `tmi-web` directory that you cloned from Github. Then type: | ||
|
|
||
| bundle | ||
|
|
||
| If you get any errors, you may need to do some searching on the web to fix your installation problems. Read the error message carefully to see which Ruby gem is having trouble being installed, and search for that along with the name and version of your operating system. | ||
|
|
||
| Take heart! If everything goes smoothly, you're all set. And if something went wrong, diagnosing the installation will be the hardest part, and it's all smooth going from there. | ||
|
|
||
| ### Prepare the Postgres database | ||
| ### Prepare the PostgreSQL database | ||
|
|
||
| From your local terminal, run the following commands: | ||
| From the root `tmi-web` directory, run the following commands: | ||
|
|
||
| rake db:create | ||
| rake db:migrate | ||
|
|
||
| If you get an error, check that postgres is running on your system. | ||
| If you get an error, check that postgresql is running on your system. | ||
|
|
||
| ### Prepare the Neo4j database | ||
|
|
||
| From your local terminal, type: | ||
| From the root directory of `tmi-web`, type: | ||
|
|
||
| rake neo4j:migrate | ||
|
|
||
|
|
@@ -75,19 +95,19 @@ Before you start the application for the first time, there are some global envir | |
|
|
||
| *IMPORTANT* This file will contain your sensitive API keys, so you want to keep it secure. Do not commit the `.env` to a source code repository, even a private one. | ||
|
|
||
| To create your local `.env` file, make a copy of `.env.example`. (Since this filename starts with a `.`, it will be hidden by default. Use `ls -a` in your terminal to list all files in the directory, including invisible ones.) In the root directory of tmi-web, type | ||
| To create your local `.env` file, make a copy of `.env.example`. (Since this filename starts with a `.`, it will be hidden by default. Use `ls -a` in your terminal to list all files in the directory, including invisible ones.) In the root directory of tmi-web, type: | ||
|
|
||
| cp .env.example .env | ||
|
|
||
| When you open the file in your editor, you'll see a list of key/value pairs that need filling in. Most of these are the API keys that TMI-Web needs to communicate with third-party services. Follow the instructions provided in the file to register for the appropriate API keys. | ||
| Now, when you open the `.env` file in your text editor, you'll see a list of key/value pairs that need filling in. These are configuration options including database credentials, customizations, and the API keys that TMI-Web needs to communicate with third-party services. Follow the instructions provided in the file to register for the appropriate API keys. | ||
|
|
||
| ### Start the background job runner | ||
|
|
||
| From the root directory of tmi-web, launch Sidekiq by typing | ||
| From the root directory of tmi-web, launch Sidekiq by typing: | ||
|
|
||
| bundle exec sidekiq | ||
| bundle exec sidekiq | ||
|
|
||
| You will see the log files for Sidekiq scroll into view. Sidekiq will continue running in the background until you terminate it with control-c. | ||
| You will see the log files for Sidekiq scroll into view. Sidekiq will continue running in the background until you terminate it with `control-c`. | ||
|
|
||
| ### Start the application | ||
|
|
||
|
|
@@ -97,62 +117,64 @@ To start TMI-web, type | |
|
|
||
| You should see the output logs from the application begin to scroll into view. The application will continue running in that terminal shell until you interrupt the process (with cmd-c) or otherwise terminate the application. Shutting down the application can be safely done at any time. | ||
|
|
||
| Now that the application has been started, visit [http://localhost:3000 | ||
| ](http://localhost:3000) in your web browser. | ||
| Now that the application has been started, visit [http://localhost:3000](http://localhost:3000) in your web browser. | ||
|
|
||
| ### What to do if the homepage times out | ||
| ### What to do if the application doesn't start | ||
|
|
||
| If you forgot to launch the Neo4j application and start the tmi_graph database, the Rails application will try to connect for 30+ seconds and then time out. You'll always need to keep Neo4j running in the background while you're using TMI-Web in your local environment. | ||
| If you forgot to open the Neo4j application and start the `tmi_graph` database, the Rails application will hang as it tries to connect, and time out after 60 seconds. You'll always need to keep Neo4j running in the background while you're using TMI-Web in your local environment. | ||
|
|
||
| You may get an error that has to do with database migrations. You may be missing changes to the database structure from the last time you ran the application. | ||
| You may get an error that has to do with database migrations. This means that your local database is missing updates and changes to the database structure since the last time you ran the application. | ||
|
|
||
| To update the Postgresql database, from the root directory of tmi-web type | ||
| To update the Postgresql database, from the root directory of `tmi-web` type: | ||
|
|
||
| rake db:migrate | ||
|
|
||
| To update the Neo4j database, type | ||
| To update the Neo4j database, type: | ||
|
|
||
| rake neo4j:migrate | ||
|
|
||
| ## Developer tips | ||
|
|
||
| ### Clear the sidekiq (background job) queue | ||
| ### Clear the Sidekiq (background job) queue | ||
|
|
||
| Sidekiq.redis(&:flushdb) | ||
| Launch the local interactive Rails console: | ||
|
|
||
| ### Back up production postgresql database | ||
| bin/rails console | ||
|
|
||
| Navigate in your terminal to the `db` directory and run these commands | ||
| At the prompt, type: | ||
|
|
||
| heroku pg:backups:capture --app tmi-web | ||
| heroku pg:backups:download --app tmi-web | ||
| Sidekiq.redis(&:flushdb) | ||
|
|
||
| ### Restore production postgresql database to last db capture | ||
| To exit the console: | ||
|
|
||
| Navigate in your terminal to the `db` directory and run these commands | ||
| exit | ||
|
|
||
| ### Back up production PostgresSQL database | ||
|
|
||
| heroku pg:backups:restore --app tmi-web | ||
| Navigate in your terminal to the `db` directory and run these commands: | ||
|
|
||
| ### Load postgresql database backup into local db | ||
| heroku pg:backups:capture --app tmi-web | ||
| heroku pg:backups:download --app tmi-web | ||
|
|
||
| Navigate in your terminal to the `db` directory and type | ||
| ### Restore production PostgresSQL database to last db capture | ||
|
|
||
| pg_restore --verbose --clean --no-acl --no-owner -h localhost -U postgres -d tmi_web_development db/latest.dump | ||
| heroku pg:backups:restore --app tmi-web | ||
|
|
||
| ### Update neo4j schema | ||
| ### Load PostgresSQL database backup into local db | ||
|
|
||
| rake neo4j:migrate | ||
| Navigate in your terminal to the `db` directory and type | ||
|
|
||
| ### Generate rdocs | ||
| pg_restore --verbose --clean --no-acl --no-owner -h localhost -U postgres -d tmi_web_development db/latest.dump | ||
|
|
||
| rdoc -op doc | ||
| ### Update the Neo4j database schema | ||
|
|
||
| ## Links | ||
| rake neo4j:migrate | ||
|
|
||
| ### neo4j hosting | ||
| ### Generate code documentation | ||
|
|
||
| https://console.neo4j.io | ||
| rdoc -op doc | ||
|
|
||
| ### OpenAI API dashboard | ||
| ## Reference links | ||
|
|
||
| https://platform.openai.com | ||
| * [https://console.neo4j.io](https://console.neo4j.io) | ||
| * [https://platform.openai.com](https://console.neo4j.io) | ||