Homepage

Appearance

Getting Started ​

Prerequisites ​

  • Node.js 20+
  • npm
  • Docker and Docker Compose (for production deployment)

Installation ​

1. Clone the repository ​

bash
git clone https://codeberg.org/thelinuxcast/Homepage.git
cd Homepage

2. Install dependencies ​

bash
# Root dependencies
npm install

# Client dependencies
cd client && npm install && cd ..

# Server dependencies
cd server && npm install && cd ..

3. Configure environment ​

bash
cp .env.example .env

Edit .env with your settings. At minimum, set PORT and NODE_ENV. See the Configuration page for all available options.

4. Start the development server ​

bash
npm run dev

This starts:

  • Client at http://localhost:3000 (Vite dev server with HMR)
  • Server at http://localhost:3001 (Express API)

The client proxies API requests to the server automatically.

Project structure ​

homepage/
├── client/          # React + Vite frontend
│   └── src/
│       ├── components/widgets/   # One file per widget
│       ├── store/useStore.ts     # Zustand global state
│       ├── services/api.ts       # API client
│       └── types/index.ts        # Shared TypeScript types
├── server/          # Express backend
│   └── src/
│       ├── routes/api.routes.ts  # All API endpoints
│       ├── services/             # Per-integration service modules
│       └── database.ts           # SQLite setup & migrations
├── data/            # SQLite database (created on first run)
│   └── homepage.db
└── docs/            # This documentation

First run ​

On the first run with no database, the app initialises all widgets with their default configurations. You will see a full grid of widgets, most of which will show a "not configured" state until you add API keys via Settings → Widgets.

To open Settings, click the gear icon in the header or press ?.

Personal Homepage Dashboard