P4E-P4SBU-SBU07

This manual outlines the step-by-step instructions for installing, configuring, and starting the server side and frontend of the project.

Note: Some settings are hardcoded in the application, such as the Django SECRET_KEY and database credentials (see the DATABASES section in settings.py). You may need to update these values before deploying in production.

---

Table of Contents

• Overview
• Installation on Linux
• Installation on macOS
• Installation on Windows
• Database Setup
• Configuring Django Settings
• Running the Application
• Hardcoded Constants
• Troubleshooting and References
• Frontend Setup

---

Note: Currently, this project works best on Linux/WSL enviornments.

Overview

Parking management system for reserving spaces on a college campus.

Installation on Linux

1. Update System and Install Dependencies

Open your terminal and run the following commands (on non-root user):

sudo apt update
sudo apt upgrade -y

Then install the necessary packages:

sudo apt install postgresql postgresql-contrib postgis libgdal-dev python3 python3-pip python3-venv

2. Configure PostgreSQL and PostGIS

Switch to the postgres user:

sudo -i -u postgres

Create a PostgreSQL user (if needed) and the database:

createuser --interactive
createdb p4edb

Enable the PostGIS extension:

psql -d p4edb -c "CREATE EXTENSION postgis;"

Exit the postgres user shell:

exit

3. Set Up Python Virtual Environment and Install Python Packages

Create and activate a virtual environment:

python3 -m venv venv
source venv/bin/activate

Upgrade pip and install the required Python packages:

pip install --upgrade pip
pip install -r path/to/P4SBU/folder/server/requirements.txt

---

Installation on macOS

1. Install Homebrew (if not already installed)

Open Terminal and run:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. Install Dependencies via Homebrew

Install PostgreSQL and PostGIS:

brew install postgresql postgis

Install GDAL and GEOS:

brew install gdal geos

Install Python3 (if needed):

brew install python

3. Start PostgreSQL and Configure Database

Start the PostgreSQL service:

brew services start postgresql

Create a new database and user (adjust <username> as needed):

createuser -s <username>
createdb p4edb
psql -d p4edb -c "CREATE EXTENSION postgis;"

4. Set Up Python Virtual Environment and Install Python Packages

Create and activate a virtual environment:

python3 -m venv venv
source venv/bin/activate

Upgrade pip and install dependencies:

pip install --upgrade pip
pip install -r path/to/P4SBU/folder/server/requirements.txt

---

Installation on Windows

1. Install Required Software

• Python: Download and install Python. Make sure to check "Add Python to PATH" during installation.
• PostgreSQL: Download and install PostgreSQL. During installation, ensure that PostGIS is selected as an additional component.
• GDAL & GEOS: Install OSGeo4W from OSGeo4W. During the setup, install the GDAL and GEOS packages.

2. Configure PostgreSQL and PostGIS

Using the SQL Shell (psql) or pgAdmin, create your database and enable PostGIS:

CREATE DATABASE p4edb;
\c p4edb
CREATE EXTENSION postgis;

3. Set Up Python Virtual Environment and Install Python Packages

Open Command Prompt or PowerShell and run:

python -m venv venv
venv\Scripts\activate

Upgrade pip and install required packages:

py -m pip install --upgrade pip
py -m pip install -r path/to/P4SBU/folder/server/requirements.txt

Important: Make sure the GDAL and GEOS library paths in your settings.py are correctly set for Windows:

GDAL_LIBRARY_PATH = r'C:\OSGeo4W\bin\gdal310.dll'
GEOS_LIBRARY_PATH = r'C:\OSGeo4W\bin\geos_c.dll'

---

Database Setup

• Database Name: p4edb
• User: sbu7
• Password: trvclearfission777@
• Host: localhost
• Port: 5432

These credentials are specified in the DATABASES configuration in settings.py. If necessary, update these values in settings.py for your deployment environment.

---

Configuring Django Settings

Review the settings.py file (located in the project root) for key configurations:

• Secret Key:
  SECRET_KEY = 'django-insecure-vr&bee(#$(f@hsljd#jzoarqhub0$%i3^zz+cvhu!a=&c+d-z#'
  Update this key for production.

• Debug Mode:
  DEBUG = True
  Set to False in production environments.

• Database Settings:
  The database connection details (name, user, password, etc.) are hardcoded. Update as needed.

• GDAL & GEOS:
  Library paths are set conditionally based on the operating system. Verify that the paths match your installation:

  • Windows:

    GDAL_LIBRARY_PATH = r'C:\OSGeo4W\bin\gdal310.dll'
    GEOS_LIBRARY_PATH = r'C:\OSGeo4W\bin\geos_c.dll'

  • macOS:

    GDAL_LIBRARY_PATH = '/opt/homebrew/lib/libgdal.dylib'
    GEOS_LIBRARY_PATH = '/opt/homebrew/lib/libgeos_c.dylib'

  • Linux:

    GDAL_LIBRARY_PATH = '/usr/lib/x86_64-linux-gnu/libgdal.so'
    GEOS_LIBRARY_PATH = '/usr/lib/x86_64-linux-gnu/libgeos_c.so'

• CORS Settings:
  The settings allow all origins for development. Modify CORS_ALLOW_ALL_ORIGINS and CORS_ALLOWED_ORIGINS for production use.

---

Running the Application

1. Apply Database Migrations

After setting up the virtual environment and configuring the database, run:

python manage.py makemigrations
python manage.py migrate

2. Create a Superuser (Optional)

To access the Django admin interface:

python manage.py createsuperuser

3. Start the Django Development Server

Run the server:

python manage.py runserver

The application will be accessible at http://127.0.0.1:8000/.

---

Hardcoded Constants

The following constants are hardcoded in the code and may need updating:

• SECRET_KEY in settings.py
• Database Credentials:
  • Database Name: p4edb
  • User: sbu7
  • Password: trvclearfission777@

Please update these values in settings.py under the DATABASES section and the top of the file before starting the server.

---

Troubleshooting and References

• Documentation:

  • Django Documentation
  • GeoDjango Documentation
  • PostGIS Documentation
  • GDAL Documentation
  • OSGeo4W Downloads

• Common Issues:

  • Verify that PostgreSQL is running and that you have created the p4edb database.
  • Check that the GDAL and GEOS library paths in settings.py match the installation directories on your system.
  • Ensure your Python virtual environment is activated before running Django commands.
  • Ensure you are not using the root user for Linux (use whoami command)

If you encounter dependency conflicts or errors during installation, try either steps: (or both)

• Try Installation on Linux again with a fresh install of WSL2
• Use Poetry with the provided poetry.lock file. This file ensures that the exact tested package versions are installed.

1. Ensure Poetry is Installed

• Linux/macOS: Open your terminal and run:

  curl -sSL https://install.python-poetry.org | python3 -

  Follow any additional instructions (such as adding Poetry to your PATH) provided by the installer.

• Windows: Open PowerShell and run:

  (Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python -

  Alternatively, download and run the installer from the Poetry installation page.

2. Install Dependencies Using Poetry

In the root directory of your project (where the poetry.lock file is located), run:

poetry install

This command will install all dependencies according to the versions specified in poetry.lock.

3. Troubleshooting Dependency Issues

• Update the Lock File (Without Updating Versions): If you run into conflicts, try:

  poetry lock --no-update

• Regenerate the Lock File: If issues persist, you can remove the existing lock file and regenerate it:

  • Linux/macOS:

    rm poetry.lock
    poetry install

  • Windows:

    del poetry.lock
    poetry install

• Consult Documentation: For more detailed troubleshooting, refer to the Poetry documentation.

Frontend Setup

1. Ensure Node.js and npm are Installed

• Linux:
  Open your terminal and run:

  sudo apt update
  sudo apt install nodejs npm

  Alternatively, install the latest Node.js via NodeSource.

• macOS:
  If you have Homebrew installed, run:

  brew install node

• Windows:
  Download and install the latest LTS version of Node.js from the official Node.js website. Ensure npm is included with your installation.

2. Install Frontend Dependencies

Navigate to the project's root directory and run:

npm install

This command installs all the dependencies specified in the package.json file. You may also need:

npm install --legacy-peer-deps

3. Generate an Authentication Secret

After installing the dependencies, generate a secure authentication secret by running:

npx auth secret

This command will generate and display a secret key inside p4sbu/.env.local

4. Start the Frontend Server

Once the dependencies are installed and the secret has been generated, start the frontend server by running:

npm run dev

or

npm run build
npm run start

After the server starts, open your web browser and navigate to http://localhost:3000 to view the application.

If you encounter any issues during this process, please consult the npm documentation or the Node.js website.