Installation

Step-by-step guide for installing and setting up your Residents instance.

This section provides a guide on how to install and set up our project on your local machine or server.

Getting Started Locally

Follow these steps to set up and run the Residents app on your local machine:

1

Clone the Repository

git clone https://github.com/conorluddy/Residents

cd Residents
2

Install Dependencies

npm install
3

Set Up Environment Variables

  • Copy the example environment file:

    cp .env.example .env

  • Open the .env file and update the variables with your own values, especially:

    • Database connection details (POSTGRES)
    • JWT secret (JWT_TOKEN_SECRET)
    • Google OAuth credentials (if using Google login)
    • SendGrid API key (if using email functionality to send invites/reset/magic emails)
4

Set Up the Database

  • Ensure you have PostgreSQL installed and running
  • Create a new database matching the POSTGRES_DB in your .env file
  • Initialize the database schema: 
    npm run push
5

Optional: Seed the Database

To populate the database with sample data:

npm run seed

To create an initial admin user. This will use the values defined in your .env to set the user details, including the password, of the first user.

npm run seed:owner
6

Start the Development Server

npm run dev
7

Access the API

  • The API should now be running on http://localhost:3000 (or the port specified in your .env file)
  • Swagger API documentation is available at http://localhost:3000/api-docs
  • Swagger/OpenAPI as JSON is available at http://localhost:3000/api-json
8

Running Tests

npm test
9

Using Docker (Optional)

If you prefer to use Docker:

  • Ensure Docker is installed on your system
  • Run: 
    docker-compose up

This will start both the PostgreSQL database and the application in containers.

Additional Notes

  • For Google authentication, ensure you've set up a Google Developer account and obtained the necessary credentials.
  • For email functionality (password resets, etc.), make sure you've set up a SendGrid account and verified your sender email.
  • The application uses various environment variables for configuration. Refer to the .env.example file for all required variables.
  • TypeScript is used for development. The npm run build command compiles the TypeScript code to JavaScript.

Troubleshooting

  • If you encounter any database connection issues, double-check your PostgreSQL settings and ensure the service is running.
  • For any dependency-related errors, try deleting the node_modules folder and running npm install again.
  • Ensure all required environment variables are properly set in your .env file.

For more detailed information on the project structure, available API endpoints, and future development plans, refer to the full README in the project repository.