195 lines
6.1 KiB
Markdown
195 lines
6.1 KiB
Markdown
# NocoDB Map Viewer
|
||
|
||
A containerized web application that visualizes geographic data from NocoDB on an interactive map using Leaflet.js.
|
||
|
||
## Features
|
||
|
||
- 🗺️ Interactive map visualization with OpenStreetMap
|
||
- 📍 Real-time geolocation support
|
||
- ➕ Add new locations directly from the map
|
||
- 🔄 Auto-refresh every 30 seconds
|
||
- 📱 Responsive design for mobile devices
|
||
- 🔒 Secure API proxy to protect credentials
|
||
- 👤 User authentication with login system
|
||
- ⚙️ Admin panel for system configuration
|
||
- 🎯 Configurable map start location
|
||
- 🐳 Docker containerization for easy deployment
|
||
- 🆓 100% open source (no proprietary dependencies)
|
||
|
||
## Quick Start
|
||
|
||
### Prerequisites
|
||
|
||
- Docker and Docker Compose
|
||
- NocoDB instance with a table containing location data
|
||
- NocoDB API token
|
||
|
||
### NocoDB Table Setup
|
||
|
||
1. **Main Locations Table** - Create a table with these required columns:
|
||
- `Geo-Location` (Text): Format "latitude;longitude"
|
||
- `latitude` (Decimal): Precision 10, Scale 8
|
||
- `longitude` (Decimal): Precision 11, Scale 8
|
||
- `title` (Text): Location name
|
||
- `category` (Single Select): Classification
|
||
|
||
2. **Login Table** - Create a table for user authentication:
|
||
- `Email` (Email): User email address
|
||
- `Name` (Single Line Text): User display name
|
||
- `Admin` (Checkbox): Admin privileges
|
||
|
||
3. **Settings Table** - Create a table for admin configuration:
|
||
- `key` (Single Line Text): Setting identifier
|
||
- `title` (Single Line Text): Display name
|
||
- `Geo-Location` (Text): Format "latitude;longitude"
|
||
- `latitude` (Decimal): Precision 10, Scale 8
|
||
- `longitude` (Decimal): Precision 11, Scale 8
|
||
- `zoom` (Number): Map zoom level
|
||
- `category` (Single Select): "system_setting"
|
||
- `updated_by` (Single Line Text): Last updater email
|
||
- `updated_at` (DateTime): Last update time
|
||
|
||
### Installation
|
||
|
||
1. Clone this repository or create the file structure as shown
|
||
|
||
2. Copy the environment template:
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
3. Edit `.env` with your NocoDB details:
|
||
```env
|
||
NOCODB_API_URL=https://db.lindalindsay.org/api/v1
|
||
NOCODB_API_TOKEN=your-token-here
|
||
NOCODB_VIEW_URL=https://db.lindalindsay.org/dashboard/#/nc/p406kno3lbq4zmq/mvtryxrvze6td79
|
||
NOCODB_LOGIN_SHEET=https://db.lindalindsay.org/dashboard/#/nc/p406kno3lbq4zmq/login_sheet_id
|
||
NOCODB_SETTINGS_SHEET=https://db.lindalindsay.org/dashboard/#/nc/p406kno3lbq4zmq/settings_sheet_id
|
||
```
|
||
|
||
4. Start the application:
|
||
```bash
|
||
docker-compose up -d
|
||
```
|
||
|
||
5. Access the map at: http://localhost:3000
|
||
|
||
## Finding NocoDB IDs
|
||
|
||
### API Token
|
||
1. Click user icon → Account Settings
|
||
2. Go to "API Tokens" tab
|
||
3. Create new token with read/write permissions
|
||
|
||
### Project and Table IDs
|
||
- Simply provide the full NocoDB view URL in `NOCODB_VIEW_URL`
|
||
- The system will automatically extract the project and table IDs
|
||
|
||
## API Endpoints
|
||
|
||
### Public Endpoints
|
||
- `GET /api/locations` - Fetch all locations (requires auth)
|
||
- `POST /api/locations` - Create new location (requires auth)
|
||
- `GET /api/locations/:id` - Get single location (requires auth)
|
||
- `PUT /api/locations/:id` - Update location (requires auth)
|
||
- `DELETE /api/locations/:id` - Delete location (requires auth)
|
||
- `GET /api/config/start-location` - Get map start location
|
||
- `GET /health` - Health check
|
||
|
||
### Authentication Endpoints
|
||
- `POST /api/auth/login` - User login
|
||
- `GET /api/auth/check` - Check authentication status
|
||
- `POST /api/auth/logout` - User logout
|
||
|
||
### Admin Endpoints (requires admin privileges)
|
||
- `GET /api/admin/start-location` - Get start location with source info
|
||
- `POST /api/admin/start-location` - Update map start location
|
||
|
||
## Admin Panel
|
||
|
||
Users with admin privileges can access the admin panel at `/admin.html` to configure system settings.
|
||
|
||
### Features
|
||
- **Start Location Configuration**: Set the default map center and zoom level for all users
|
||
- **Interactive Map**: Visual interface for selecting coordinates
|
||
- **Real-time Preview**: See changes immediately on the admin map
|
||
- **Validation**: Built-in coordinate and zoom level validation
|
||
|
||
### Access Control
|
||
- Admin access is controlled via the `Admin` checkbox in the Login table
|
||
- Only authenticated users with admin privileges can access `/admin.html`
|
||
- Admin status is checked on every request to admin endpoints
|
||
|
||
### Start Location Priority
|
||
The system uses a cascading fallback system for map start location:
|
||
1. **Database**: Admin-configured location stored in Settings table (highest priority)
|
||
2. **Environment**: Default values from .env file (medium priority)
|
||
3. **Hardcoded**: Edmonton, Canada coordinates (lowest priority)
|
||
|
||
## Configuration
|
||
|
||
All configuration is done via environment variables:
|
||
|
||
| Variable | Description | Default |
|
||
|----------|-------------|---------|
|
||
| `NOCODB_API_URL` | NocoDB API base URL | Required |
|
||
| `NOCODB_API_TOKEN` | API authentication token | Required |
|
||
| `NOCODB_VIEW_URL` | Full NocoDB view URL | Required |
|
||
| `NOCODB_LOGIN_SHEET` | Login table URL for authentication | Required |
|
||
| `NOCODB_SETTINGS_SHEET` | Settings table URL for admin config | Optional |
|
||
| `PORT` | Server port | 3000 |
|
||
| `DEFAULT_LAT` | Default map latitude | 53.5461 |
|
||
| `DEFAULT_LNG` | Default map longitude | -113.4938 |
|
||
| `DEFAULT_ZOOM` | Default map zoom level | 11 |
|
||
|
||
## Development
|
||
|
||
To run in development mode:
|
||
|
||
1. Install dependencies:
|
||
```bash
|
||
cd app
|
||
npm install
|
||
```
|
||
|
||
2. Start with hot reload:
|
||
```bash
|
||
npm run dev
|
||
```
|
||
|
||
## Security Considerations
|
||
|
||
- API tokens are kept server-side only
|
||
- CORS is configured for security
|
||
- Rate limiting prevents abuse
|
||
- Input validation on all endpoints
|
||
- Helmet.js for security headers
|
||
|
||
## Troubleshooting
|
||
|
||
### Locations not showing
|
||
- Verify table has `geodata`, `latitude`, and `longitude` columns
|
||
- Check that coordinates are valid numbers
|
||
- Ensure API token has read permissions
|
||
|
||
### Cannot add locations
|
||
- Verify API token has write permissions
|
||
- Check browser console for errors
|
||
- Ensure coordinates are within valid ranges
|
||
|
||
### Connection errors
|
||
- Verify NocoDB instance is accessible
|
||
- Check API URL format
|
||
- Confirm network connectivity
|
||
|
||
## License
|
||
|
||
MIT License - See LICENSE file for details
|
||
|
||
## Support
|
||
|
||
For issues or questions:
|
||
1. Check the troubleshooting section
|
||
2. Review NocoDB documentation
|
||
3. Open an issue on GitHub
|