{"id":21315506,"url":"https://github.com/matiasdelellis/facerecognition-external-model","last_synced_at":"2025-07-12T01:31:30.450Z","repository":{"id":40380320,"uuid":"315109044","full_name":"matiasdelellis/facerecognition-external-model","owner":"matiasdelellis","description":"Nextcloud Facerecognition External Model","archived":false,"fork":false,"pushed_at":"2024-10-07T14:34:47.000Z","size":46,"stargazers_count":25,"open_issues_count":13,"forks_count":15,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-07-09T05:11:47.976Z","etag":null,"topics":["dlib","face-recognition"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/matiasdelellis.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2020-11-22T18:50:26.000Z","updated_at":"2025-05-05T19:13:49.000Z","dependencies_parsed_at":"2024-01-15T16:11:08.537Z","dependency_job_id":"223c998f-4713-4d79-82f6-65348b10ff01","html_url":"https://github.com/matiasdelellis/facerecognition-external-model","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/matiasdelellis/facerecognition-external-model","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matiasdelellis%2Ffacerecognition-external-model","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matiasdelellis%2Ffacerecognition-external-model/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matiasdelellis%2Ffacerecognition-external-model/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matiasdelellis%2Ffacerecognition-external-model/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/matiasdelellis","download_url":"https://codeload.github.com/matiasdelellis/facerecognition-external-model/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matiasdelellis%2Ffacerecognition-external-model/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264923080,"owners_count":23683716,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["dlib","face-recognition"],"created_at":"2024-11-21T18:21:01.007Z","updated_at":"2025-07-12T01:31:30.165Z","avatar_url":"https://github.com/matiasdelellis.png","language":"Python","readme":"# Face Recognition External Model 👪\nThis service implements the same [models](https://github.com/matiasdelellis/facerecognition/wiki/Models) that already exists in the Nextcloud [Face Recognition](https://github.com/matiasdelellis/facerecognition) application, but it allows to run it on an external machine, which can be faster, and thus free up important resources from the server where you have Nextcloud installed.\n\nTake this also as a reference model, since you can implement any external model for the Nextcloud Face Recognition application. You can implement an external model using your favorite machine learning tool, with the programming language you love.. ❤️\n\n## Privacy\nTake into account how the service works. You must send a copy of each of your images (or of your clients), from your Nextcloud instance to the server where you run this service.\nThe image files are sent via POST, and are immediately deleted after being analyzed. The shared API key is sent in the headers of each queries. This is only as secure as the connection between the two communicating devices. If you run it outside your local network, you should minimally use it behind an HTTPS proxy, which protects your data.\n\nSo, please. Think seriously about data security before running this service outside of your local network. 😉\n\n## Usage\n### API key\nAn shared API key is used to control access to the service. It can be any alphanumeric key, but it is recommended to create it automatically.\n```sh\n[matias@services ~]$ openssl rand -base64 32 \u003e api.key\n[matias@services ~]$ cat api.key \nNZ9ciQuH0djnyyTcsDhNL7so6SVrR01znNnv0iXLrSk=\n```\n\n### Docker\nThe fastest way to get this up and running without manual installation and configuration is a docker image. You only have to define the api key and the exposed port:\n```sh\n# Expose the service on 8080 TCP port and send the API key as a file. By default it uses model 4 for facial recognition.\n[matias@services ~]$ docker run --rm -i -p 8080:5000 -v /path/to/api.key:/app/api.key --name facerecognition matiasdelellis/facerecognition-external-model:v0.2.0\n# You can pass the API key as an environment variable, but it is a practice that is not recommended because it is exposed on the command line.\n[matias@services ~]$ docker run --rm -i -p 8080:5000 -e API_KEY=\"NZ9ciQuH0djnyyTcsDhNL7so6SVrR01znNnv0iXLrSk=\" --name facerecognition matiasdelellis/facerecognition-external-model:v0.2.0\n# You can change the default model using the `FACE_MODEL` environment variable.\n# If you do not set the API key, it remains \"some-super-secret-api-key\". Needless to say, it is not advisable to leave it by default.\n[matias@services ~]$ docker run --rm -i -p 8080:5000 -e FACE_MODEL=3 --name facerecognition matiasdelellis/facerecognition-external-model:v0.2.0 \n```\nIf you want to use multiple connections at once (enough memory is mandatory), either for multiple instances or for faster procession large amounts of photos (only a single core is used for each process) you can set the enviroment variable \"GUNICORN_WORKERS\" to the desired number.\n\n### Test\nCheck that the service is running using the `/welcome` endpoint.\n```sh\n[matias@services ~]$ curl localhost:8080/welcome\n{\"facerecognition-external-model\":\"welcome\",\"model\":3,\"version\":\"0.2.0\"}\n```\n\nYou must obtain the IP where you run the service.\n```sh\n[matias@services facerecognition-external-model]$ hostname -I\n192.168.1.123\n```\n\n...and do the same test on the server that hosts your nextcloud instance.\n```sh\n[matias@cloud ~]$ curl 192.168.1.123:8080/welcome\n{\"facerecognition-external-model\":\"welcome\",\"model\":3,\"version\":\"0.2.0\"}\n```\n\n## Configure Nextcloud\nIf the service is accessible, you can now configure Nextcloud indicating that you have an external model at this address, and the API key used to communicate with it.\n```sh\n[matias@cloud nextcloud]$ php occ config:system:set facerecognition.external_model_url --value 192.168.1.123:8080\nSystem config value facerecognition.external_model_url set to string 192.168.1.123:8080\n[matias@cloud nextcloud]$ php occ config:system:set facerecognition.external_model_api_key --value NZ9ciQuH0djnyyTcsDhNL7so6SVrR01znNnv0iXLrSk=\nSystem config value facerecognition.external_model_api_key set to string NZ9ciQuH0djnyyTcsDhNL7so6SVrR01znNnv0iXLrSk=\n```\n\nYou can now configure the external model (which is the 5), in the same way that it did until now.\n```\n[matias@cloud nextcloud]$ php occ face:setup -m 5\nThe files of model 5 (ExternalModel) are already installed\nThe model 5 (ExternalModel) was configured as default\n```\n\n... and that's all my friends. You can now continue with the backgroud_task. :smiley:\n\nOr if you want to use parallel processing during an import:\n```sh\n#!/bin/bash\n\nset -o errexit\n\ndir=$(pwd)\n# your nextcloud path\ncd /var/www/nextcloud/html/\nsudo -u www-data php --define apc.enable_cli=1 ./occ face:stats\n\necho -n \"Select user for import \u0026 parallel processing:\"\nread user\necho \"\"\n\necho \"Enabling facerecognition for $user...\"\nsudo -u www-data php --define apc.enable_cli=1 ./occ user:setting $user facerecognition enabled true\necho \"Done\"\n\necho \"Synchronizing $user files...\"\nsudo -u www-data php --define apc.enable_cli=1 ./occ face:background_job -u $user --sync-mode\necho \"Done\"\n\necho \"Analyzing $user files...\"\n# the upper number has to be lower or equal to the number of GUNICORN_WORKERS\nfor i in {1..3}; do\n    sudo -u www-data php --define apc.enable_cli=1 ./occ face:background_job -u $user --analyze-mode \u0026\n    pids[${i}]=$!\ndone\n\nfor pid in ${pids[*]}; do\n    wait $pid\ndone\necho \"Done\"\n\necho \"Calculating $user face clusters...\"\nsudo -u www-data php --define apc.enable_cli=1 ./occ face:background_job -u user --cluster-mode\necho \"Done\"\ncd $dir\n```\nThat runs quite long, best runing it inside a tmux/screen session.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatiasdelellis%2Ffacerecognition-external-model","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmatiasdelellis%2Ffacerecognition-external-model","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatiasdelellis%2Ffacerecognition-external-model/lists"}