{"id":13562695,"url":"https://github.com/thevahidal/soul","last_synced_at":"2025-05-14T02:04:50.323Z","repository":{"id":61238743,"uuid":"546207454","full_name":"thevahidal/soul","owner":"thevahidal","description":"🕉 Soul | Automatic SQLite RESTful  and realtime API server | Build CRUD APIs in minutes!","archived":false,"fork":false,"pushed_at":"2025-03-28T22:52:27.000Z","size":1329,"stargazers_count":1576,"open_issues_count":9,"forks_count":53,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-05-09T01:11:34.357Z","etag":null,"topics":["nodejs","realtime","rest","sqlite","sqlite3"],"latest_commit_sha":null,"homepage":"https://thevahidal.github.io/soul/","language":"JavaScript","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/thevahidal.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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":"2022-10-05T18:00:26.000Z","updated_at":"2025-05-06T18:44:42.000Z","dependencies_parsed_at":"2023-12-07T12:31:52.493Z","dependency_job_id":"df590733-afed-43a4-8a03-edcb1bc18e2e","html_url":"https://github.com/thevahidal/soul","commit_stats":{"total_commits":51,"total_committers":2,"mean_commits":25.5,"dds":"0.039215686274509776","last_synced_commit":"9ff49c7d286801bed6b50e9d41244473f51adeba"},"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thevahidal%2Fsoul","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thevahidal%2Fsoul/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thevahidal%2Fsoul/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thevahidal%2Fsoul/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thevahidal","download_url":"https://codeload.github.com/thevahidal/soul/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254052669,"owners_count":22006716,"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":["nodejs","realtime","rest","sqlite","sqlite3"],"created_at":"2024-08-01T13:01:11.303Z","updated_at":"2025-05-14T02:04:50.293Z","avatar_url":"https://github.com/thevahidal.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","sqlite","\u003ca name=\"data-management-tabular\"\u003e\u003c/a\u003eData management - Tabular data","API"],"sub_categories":["Samples"],"readme":"\u003cp align=\"center\"\u003e\n    \u003cimg src='docs/logo.png' height='150px' style=\"\"\u003e\n    \u003cp align=\"center\"\u003e\n        A SQLite REST and Realtime server\n    \u003c/p\u003e\n\u003c/p\u003e\n\n[![justforfunnoreally.dev badge](https://img.shields.io/badge/justforfunnoreally-dev-9ff)](https://justforfunnoreally.dev)\n[![All Contributors](https://img.shields.io/github/all-contributors/thevahidal/soul?color=ee8449\u0026style=flat-square)](#contributors)\n\n## Usage\n\n### Docker\n\n\u003e This is the preferred method as the dependency [better-sqlite3](https://github.com/WiseLibs/better-sqlite3) is making of lot of assumptions about the system it will be installed and running on which in most cases will lead to errors when installing soul.\n\nUsing the following Dockerfile:\n\n\u003cdetails\u003e\n  \u003csummary\u003eDockerfile\u003c/summary\u003e\n  \n  ```nginx\n# node:19-alpine amd64\nFROM node@sha256:d0ba7111bc031323ce2706f8e424afc868db289ba40ff55b05561cf59c123be1 AS node\n\nWORKDIR /app\n\nENV NODE_ENV=\"production\"\n\nCOPY package-lock.json package.json ./\n\nRUN apk update \u0026\u0026 apk add python3=3.11.10-r1 build-base=0.5-r3 \u0026\u0026 npm ci\n\nCOPY . .\n\nCMD [ \"npm\", \"start\" ]\n  ```\n\u003c/details\u003e\n\nYou can proceed [to building the application](https://docs.docker.com/get-started/workshop/02_our_app/#build-the-apps-image).\n\n### npm\n\n```bash\n  npm install -g soul-cli\n```\n\n### 1. Running Soul\n\nSoul is command line tool, after installing it,\nRun `soul -d sqlite.db -p 8000` and it'll start a REST API on [http://localhost:8000](http://localhost:8000) and a Websocket server on [ws://localhost:8000](ws://localhost:8000).\n\n```bash\nUsage: soul [options]\n\n\nOptions:\n            --version                               Show version number                                 [boolean]\n  -d,       --database                              SQLite database file or :memory:                    [string] [required]\n  -p,       --port                                  Port to listen on                                   [number]\n  -r,       --rate-limit-enabled                    Enable rate limiting                                [boolean]\n  -c,       --cors                                  CORS whitelist origins                              [string]\n  --env,    --envpath                               Path to load .env file                              [string]\n  -a,       --auth                                  Enable authentication and authorization             [boolean]\n\n  --iuu,     --initialuserusername                   Initial user username                               [string]\n  --iup,     --initialuserpassword                   Initial user password                               [string]\n\n  --ts,      --tokensecret                           Token Secret                                        [string]\n  --atet,    --accesstokenexpirationtime             Access Token Expiration Time    (Default: 5H)       [string]\n  --rtet,    --refreshtokenexpirationtime            Refresh Token Expiration Time   (Default: 1D)       [string]\n  -S,       --studio                                 Start Soul Studio in parallel\n  --help                                             Show help\n\n```\n\nThen to test Soul is working run the following command\n\n```bash\ncurl http://localhost:8000/api/tables\n```\n\nIt should return a list of the tables inside `sqlite.db` database.\n\n### 2. Running Soul in Auth mode\n\nTo run Soul in auth mode, allowing login and signup features with authorization capabilities in your database tables, follow these steps:\n\nRun the Soul command with the necessary parameters:\n\n```\n\n  soul -d foobar.db -a --ts=\u003cyour_jwt_secret_value\u003e --atet=4H --rtet=3D --iuu=john --iup=\u003cyour_password\u003e\n\n```\n\n\u003e Note: When configuring your JWT Secret, it is recommended to use a long string value for enhanced security. It is advisable to use a secret that is at least 10 characters in length.\n\nIn this example:\n\n- The `-a` flag instructs Soul to run in auth mode.\n- The `--ts` flag allows you to pass a JWT secret value for the `access and refresh tokens` generation and verification. Replace \u003cyour_jwt_secret_value\u003e with your desired secret value.\n- The `--atet` flag sets the JWT expiration time for the access token. In this case, it is set to four hours (4H), meaning the token will expire after 4 hours.\n- The `--rtet` flag sets the JWT expiration time for the refresh token. In this case, it is set to three days (3D), meaning the token will expire after 3 days.\n- The `--iuu` flag is used to pass a username for the initial user\n- The `--iup` flag is used to pass a password for the initial user\n\nHere are some example values for the `atet` and `rtet` flags\n\n- 60M: Represents a duration of 60 minutes.\n- 5H: Represents a duration of 5 hours.\n- 1D: Represents a duration of 1 day.\n\nNOTE: It is crucial to securely store a copy of the `--ts`(`Token Secret`) value used in Soul. Once you pass this values, make sure to keep a backup because you will need it every time you restart Soul. Losing this secret values can result in a situation where all of your users are blocked from accessing Soul.\n\n### 3. Updating Super Users\n\nTo modify a superuser information in a database, you can utilize the `updatesuperuser` command. This command allows you to change a superuser's `password` or upgrade/downgrade a normal user to a `superuser`. Below is an example of how to use it:\n\n```\nsoul -d foobar.db updatesuperuser --id=1 password=\u003cnew_password_for_the_user\u003e // Update the password for the superuser with ID 1\n\nsoul -d foobar.db updatesuperuser --id=1 --is_superuser=true // Upgrade the user with ID 1 to a superuser\n\nsoul -d foobar.db updatesuperuser --id=1 --is_superuser=false // Revoke the superuser role from the superuser with ID 1\n```\n\n### Passing Custom Path for .env File\n\nThere might be cases where you want to pass a custom path for your `.env` file. For this, you can use the `--env` flag when running the `soul` command, providing the absolute file path of your `.env` file.\n\n```shell\nsoul -d foobar.db --env=/absolute/path/of/your/.env/file\n```\n\nNOTE:\n\n- You should pass an absolute file path of the .env file.\n- Relative paths are not allowed.\n- Don't forget to include the .env file in the specified path.\n\n## Documentation\n\nAPI documentation is available while the project is running at [http://localhost:8000/api/docs](http://localhost:8000/api/docs)\n\nThere's also a list of all endpoints examples at [docs/api-examples.md](docs/api-examples.md)\n\nFor websocket examples, check [docs/ws-examples.md](docs/ws-examples.md)\n\nFor detailed information on how authentication works in Soul, please refer to the [docs/auth.md](docs/auth.md)\n\n## Extending Soul\n\nSoul is able to be extended (e.g. Adding custom APIs) via extensions, you can find a list of extensions at [docs/extensions-examples.md](docs/extensions-examples.md)\n\n## Soul-mates\n\nA collection of projects that revolve around the Soul ecosystem.\n\n- [Soul Studio](https://github.com/thevahidal/soul-studio) provides a GUI to work with your database.\n\n  Right now Soul Studio is in early stages of development and not useful to work with.\n\n    \u003cp align=\"center\"\u003e\n        \u003cimg src='docs/soul-studio.png' style=\"\"\u003e\n    \u003c/p\u003e\n\n- [RCO-Soul](https://github.com/DeepBlueCLtd/RCO-Soul) The purpose of this project is to demonstrate how to run a React admin client using Soul as a REST API service.\n\n- [dber](https://github.com/findyourmagic/dber) Database design tool based on entity relation diagram\n\n## Development\n\n```bash\ngit clone https://github.com/thevahidal/soul # Clone project\n\ncp .env.sample .env # Duplicate sample environment variables\nvim .env # Update the environment variables\n\nnpm install # Install dependencies\nnpm run dev # Start the dev server\n```\n\n## Testing\n\n1. Set the `AUTH` variable to true in your `.env` file.\n2. Provide a username for the `INITIAL_USER_USERNAME` environment variable. The username should be a valid, meaningful username.\n3. Provide a strong password for the `INITIAL_USER_PASSWORD` environment variable. The password should be at least 8 characters long and contain a combination of lowercase letters, uppercase letters, numbers, and special characters, for example: \"Str0ng$Pw!\".\n4. Provider a secret for the `TOKEN_SECRET` environment variable.\n5. Use the following command to run the tests:\n\n```\n npm run test\n```\n\nMake sure to replace the placeholders with the appropriate values for your environment.\n\n## Hosting Static Content Using Soul\n\nYou can host static content using Soul by utilizing its extensions feature. This allows you to expose your static application through Soul, enabling users to access your content without hosting multiple applications. please check [this](./docs/self-hosting.md) document\n\n## Community\n\n[Join](https://bit.ly/soul-discord) the discussion in our Discord server and help making Soul together.\n\n## License\n\n[MIT](https://choosealicense.com/licenses/mit/)\n\n## Contributing\n\nContributions are always welcome!\n\nSee `CONTRIBUTING.md` for ways to get started and please adhere to `CODE OF CONDUCT`.\n\n## Contributors ✨\n\nThanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --\u003e\n\u003c!-- prettier-ignore-start --\u003e\n\u003c!-- markdownlint-disable --\u003e\n\u003ctable\u003e\n  \u003ctbody\u003e\n    \u003ctr\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"http://linktr.ee/thevahidal\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/20302825?v=4?s=100\" width=\"100px;\" alt=\"Vahid Al\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eVahid Al\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/thevahidal/soul/commits?author=thevahidal\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"https://github.com/thevahidal/soul/pulls?q=is%3Apr+reviewed-by%3Athevahidal\" title=\"Reviewed Pull Requests\"\u003e👀\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://github.com/AbegaM\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/70259638?v=4?s=100\" width=\"100px;\" alt=\"Abenezer Melkamu\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eAbenezer Melkamu\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/thevahidal/soul/commits?author=AbegaM\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://github.com/IanMayo\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/1108513?v=4?s=100\" width=\"100px;\" alt=\"Ian Mayo\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eIan Mayo\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/thevahidal/soul/commits?author=IanMayo\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"https://github.com/thevahidal/soul/pulls?q=is%3Apr+reviewed-by%3AIanMayo\" title=\"Reviewed Pull Requests\"\u003e👀\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://godot.id\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/40712686?v=4?s=100\" width=\"100px;\" alt=\"Hanz\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eHanz\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/thevahidal/soul/commits?author=HanzCEO\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://github.com/KoenDG\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/1440619?v=4?s=100\" width=\"100px;\" alt=\"Koen De Groote\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eKoen De Groote\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/thevahidal/soul/commits?author=KoenDG\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://github.com/TahaKhanAbdalli\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/50602678?v=4?s=100\" width=\"100px;\" alt=\"Muhammad Taha Khan\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eMuhammad Taha Khan\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/thevahidal/soul/commits?author=TahaKhanAbdalli\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"http://thoughtsunificator.me\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/85041649?v=4?s=100\" width=\"100px;\" alt=\"Romain Lebesle\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eRomain Lebesle\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/thevahidal/soul/commits?author=thoughtsunificator\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\n\u003c!-- markdownlint-restore --\u003e\n\u003c!-- prettier-ignore-end --\u003e\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:END --\u003e\n\nThis project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthevahidal%2Fsoul","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthevahidal%2Fsoul","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthevahidal%2Fsoul/lists"}