Getting Started

This guide will help you get UniLost up and running on your local machine.

Prerequisites

Before you begin, ensure you have the following installed:

Server Requirements:

  • Node.js: Version 18.0.0 or later (Node.js 20 LTS recommended)

  • npm: Version 9.0.0 or later

  • Database: * PostgreSQL (for production deployment) * SQLite (for local development, included with better-sqlite3)

Client Requirements:

  • Modern web browsers: * Chrome 90+ * Firefox 88+ * Safari 14+ * Edge 90+

  • Mobile browsers: * iOS Safari 14+ * Android Chrome 90+

Installation

Step 1: Clone the Repository

Clone the repository to your local machine:

git clone https://github.com/jin040907/UniLost.git
cd UniLost

Step 2: Install Dependencies

Install all required npm packages:

npm install

This will install the following dependencies:

  • express - Web framework

  • express-session - Session management

  • bcrypt - Password hashing

  • socket.io - Real-time communication

  • pg - PostgreSQL client

  • better-sqlite3 - SQLite database

Step 3: Database Setup

Choose one of the following options:

Option A: SQLite (Local Development)

SQLite is the default option for local development. No additional setup is required. The database file (unilost.db) will be created automatically when you first run the server.

Option B: PostgreSQL (Production)

For production deployment, set the DATABASE_URL environment variable:

export DATABASE_URL="postgresql://user:password@host:5432/database"

For detailed PostgreSQL setup instructions, see Configuration Guide.

Step 4: Environment Variables (Optional)

Set optional environment variables:

export PORT=3000                    # Server port (default: 3000)
export SESSION_SECRET="your-secret" # Session secret (required for production)
export NODE_ENV=production          # Environment mode

Running the Application

Start the server:

npm start

Or directly:

node server.js

The server will start and display:

http://localhost:3000

Access the Application

Open your web browser and navigate to:

http://localhost:3000

Default Accounts

The system comes with default accounts for testing:

  • Student Accounts: * Usernames: student1 ~ student10 * Password: 1234

  • Administrator Accounts: * Usernames: admin1 ~ admin10 * Password: admin123

Verification

To verify the installation:

  1. Check Server Status: The server should start without errors

  2. Access Homepage: Navigate to http://localhost:3000

  3. Test Login: Log in with one of the default accounts

  4. Check Database: Verify that the database tables are created

Troubleshooting

Common Issues:

  • Port Already in Use: Change the PORT environment variable or stop the process using port 3000

  • Database Connection Error: Verify DATABASE_URL format for PostgreSQL or check SQLite file permissions

  • Module Not Found: Run npm install again to ensure all dependencies are installed

For more troubleshooting help, see Maintenance and Troubleshooting.

Next Steps