{"id":28586709,"url":"https://github.com/lchristmann/selfhosted-tracker-backend","last_synced_at":"2026-04-11T06:03:12.487Z","repository":{"id":294869706,"uuid":"987680713","full_name":"lchristmann/selfhosted-tracker-backend","owner":"lchristmann","description":"This Selfhosted Tracker Backend provides a lightweight, containerized Laravel API for managing user profiles and associated location data for a Geolocation Tracking app.","archived":false,"fork":false,"pushed_at":"2025-06-25T17:22:48.000Z","size":279,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-25T17:42:51.566Z","etag":null,"topics":["docker","docker-compose","laravel","laravel-12","laravel-api","location-tracker","nginx","oss","php","postgresql-database","rest-api","self-hosted"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lchristmann.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-21T12:33:34.000Z","updated_at":"2025-06-25T17:22:52.000Z","dependencies_parsed_at":"2025-06-11T16:50:41.045Z","dependency_job_id":null,"html_url":"https://github.com/lchristmann/selfhosted-tracker-backend","commit_stats":null,"previous_names":["lchristmann/quokka-tracker-backend","lchristmann/selfhosted-tracker-backend"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/lchristmann/selfhosted-tracker-backend","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lchristmann%2Fselfhosted-tracker-backend","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lchristmann%2Fselfhosted-tracker-backend/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lchristmann%2Fselfhosted-tracker-backend/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lchristmann%2Fselfhosted-tracker-backend/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lchristmann","download_url":"https://codeload.github.com/lchristmann/selfhosted-tracker-backend/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lchristmann%2Fselfhosted-tracker-backend/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31670383,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-10T17:19:37.612Z","status":"online","status_checked_at":"2026-04-11T02:00:05.776Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","docker-compose","laravel","laravel-12","laravel-api","location-tracker","nginx","oss","php","postgresql-database","rest-api","self-hosted"],"created_at":"2025-06-11T07:01:01.427Z","updated_at":"2026-04-11T06:03:12.480Z","avatar_url":"https://github.com/lchristmann.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Tracker Backend \u003c!-- omit in toc --\u003e\n\n\u003e The self-hosted setup is incredibly easy - just follow the instructions in the [setup guide](docs/SETUP-GUIDE.md)\n\u003e and the tiny [upgrade guide](docs/UPGRADE-GUIDE.md).\n\n\u003e As a Tracker Administrator, consider the [admin guide](docs/ADMIN-GUIDE.md).\n\nI built this API intending to use it in an upgraded version of my Geolocation Tracking Android application called [Tracker](https://github.com/lchristmann/Tracker).\n\nSo far I did not do the upgrade though. The plan is to give it a beautiful UI using React Native + Tailwind\nand turn the location tracking core code (written in Kotlin) into a [Native Module](https://reactnative.dev/docs/turbo-native-modules-introduction)\nbecause the native Android APIs for guaranteed background work and location tracking\nare a lot more reliable than what React Native itself offers.\n\nFeel free to build your own mobile apps though and just take this API Backend.\n\nIt's pretty powerful, even supporting timezones (when a day starts and ends, depends on the timezone you're in, so that's important).\n\n## Table of Contents \u003c!-- omit in toc --\u003e\n\n- [Architecture](#architecture)\n  - [Database Schema](#database-schema)\n  - [API Schema](#api-schema)\n- [Development](#development)\n  - [Helpful commands](#helpful-commands)\n  - [Database Seeding](#database-seeding)\n- [Release](#release)\n  - [Test the new release](#test-the-new-release)\n  - [Make the new release available to the public](#make-the-new-release-available-to-the-public)\n  - [Release the Nginx Image (rarely needed)](#release-the-nginx-image-rarely-needed)\n- [Maintenance](#maintenance)\n\n## Architecture\n\nThe backend is composed of three Docker containers:\n\n- [Nginx](https://nginx.org/): Web Server\n- [PHP-FPM](https://www.php.net/manual/de/install.fpm.php): Laravel API runtime\n- [PostgreSQL](https://www.postgresql.org/): Database\n\n### Database Schema\n\n![Database schema](docs/db-schema.drawio.svg)\n\nIn addition to the application-specific tables, Laravel adds its standard tables and there's the Laravel Sanctum table `personal_access_tokens`, which stores the authentication tokens for users.\n\n### API Schema\n\nAll endpoints are protected using Laravel Sanctum's `auth:sanctum` middleware.\nClients must include their personal access token in every request.\nThis ensures secure access and enables `/me`-scoped endpoints for user-specific data.\n\n| Method | Endpoint                | Description                      | Resource |\n|--------|-------------------------|----------------------------------|----------|\n| GET    | /me                     | fetch **my** profile             | User     |\n| PUT    | /me                     | update **all my** profile        | User     |\n| PATCH  | /me                     | update **some of my** profile    | User     |\n| GET    | /me/image               | fetch **my** profile image       | User     |\n| GET    | /me/locations           | fetch **my** locations           | Location |\n| POST   | /me/locations           | upload locations **of mine**     | Location |\n|        |                         |                                  |          |\n| GET    | /users                  | fetch **all** profiles           | User     |\n| GET    | /users/{user}           | fetch **a user's** profile       | User     |\n| GET    | /users/{user}/image     | fetch **a user's** profile image | User     |\n| GET    | /users/{user}/locations | fetch **a user's** locations     | Location |\n\n**See the [API Documentation](docs/API-DOCUMENTATION.md) for detailed usage.**\n\n## Development\n\nThis project adheres to standard [Laravel](https://laravel.com/docs/12.x) conventions.\nThe development environment uses a [Docker Compose setup](docs/DOCKER-COMPOSE.md) defined in `compose.dev.yaml`,\nwhich includes an additional workspace container with helpful CLI tools.\n\n```shell\ndocker compose -f compose.dev.yaml up -d # Start the setup\n```\n\n```shell\ndocker compose -f compose.dev.yaml down # Shut it down\n```\n\nIf you want to test out the production environment locally, use the minimal `compose.prod.yaml` file (no workspace container).\nIt's basically the same as the `docker-compose.yaml` file which is offered for the easy self-hosting, but uses the local project code instead of the released image on Docker Hub.\n\nThe most complex part of the codebase is a large SQL query in `LocationController.php`. Refer to [SQL-QUERY-EXPLANATION.md](docs/SQL-QUERY-EXPLANATION.md) for an in-depth breakdown.\n\n### Helpful commands\n\n```shell\ndocker compose -f compose.dev.yaml exec workspace bash\n  composer install # run this on first checkout\n  php artisan key:generate --show # paste this on first checkout to .env and restart the setup\n  php artisan migrate # to set up the database structure\n  php artisan migrate:fresh --seed\n  php artisan tinker\n  Location::factory()-\u003ecount(2)-\u003emake()-\u003etoJson()\n  \ndocker compose -f compose.dev.yaml exec postgres bash\n  psql -d app -U laravel # password: secret\n  \\dt\n  \\d tablename\n```\n\n### Database Seeding\n\nSeeding the database generates:\n\n- `sanctum_tokens.txt`: Contains test users and their API tokens.\n- `storage/app/*.[svg|png]`: User profile images (50% chance per user).\n\n## Release\n\nThe application code must be containerized as shown within the `compose.prod.yaml` `web` service\nand published to the Docker Hub repository [leanderchristmann/tracker-backend](https://hub.docker.com/repository/docker/leanderchristmann/tracker-backend/general).\n\n```shell\ndocker login\n```\n\nSet a version that you want to release:\n\n```shell\nVERSION=1.0.0\n```\n\nThen build, tag and push the docker image:\n\n```shell\ndocker build \\\n  -f ./docker/common/php-fpm/Dockerfile \\\n  --target production \\\n  -t leanderchristmann/tracker-backend:${VERSION} \\\n  -t leanderchristmann/tracker-backend:latest \\\n  .\n```\n\n```shell\ndocker push leanderchristmann/tracker-backend:${VERSION}\ndocker push leanderchristmann/tracker-backend:latest\n```\n\nNow commit your changed code.\n\nAlso tag the Git release: \n\n```shell\ngit tag -a \"${VERSION}\" -m \"Release ${VERSION}\"\ngit push origin \"${VERSION}\"\n```\n\nFinally, [create a GitHub release](https://github.com/lchristmann/selfhosted-tracker-backend/releases) via the GitHub UI -\nit's takes the Git tag and lets you add some meta-information to it.\nGive a title like `2.1.0`, a heading like `## What's Changed` and put a bullet point list of changes.\n\n### Test the new release\n\nIn the docker-compose.yml **on your server**, bump up the version to what you've just released.\n\n```yaml\nphp-fpm:\n    image: leanderchristmann/tracker-backend:2.0.0 # increase this\n```\n\n### Make the new release available to the public\n\nMake this same adaptation (see previous section [Test the new release](#test-the-new-release)) to the `docker-compose.yaml` **in this repository** and push it (simple git commit).\nNow everybody following the setup guide, gets the new version of the Tracker Backend.\n\n```yaml\nphp-fpm:\n    image: leanderchristmann/tracker-backend:2.0.0 # increase this\n```\n\n### Release the Nginx Image (rarely needed)\n\n```shell\nVERSION=1.0.0 # Set a version that you want to release\n```\n\n```shell\ndocker build \\\n  -f ./docker/production/nginx/Dockerfile \\\n  -t leanderchristmann/tracker-backend-nginx:${VERSION} \\\n  -t leanderchristmann/tracker-backend-nginx:latest \\\n  .\n```\n\n```shell\ndocker push leanderchristmann/tracker-backend-nginx:${VERSION}\ndocker push leanderchristmann/tracker-backend-nginx:latest\n```\n\nThen put that version (`leanderchristmann/tracker-backend-nginx:X.X.X`) in the `docker-compose.yaml` file.\n\n## Maintenance\n\nThis project actively maintained by [Leander Christmann](https://github.com/lchristmann).\n\nFor questions or support, feel free to [email me](mailto:hello@lchristmann.com).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flchristmann%2Fselfhosted-tracker-backend","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flchristmann%2Fselfhosted-tracker-backend","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flchristmann%2Fselfhosted-tracker-backend/lists"}