{"id":40540875,"url":"https://github.com/indxsearch/indxcloudapi","last_synced_at":"2026-01-20T23:03:22.585Z","repository":{"id":332987361,"uuid":"1120534774","full_name":"indxSearch/IndxCloudApi","owner":"indxSearch","description":"Starter template for building a search service with Indx. Ready to deploy.","archived":false,"fork":false,"pushed_at":"2026-01-16T17:50:27.000Z","size":539,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-17T05:40:37.766Z","etag":null,"topics":["asp-net","autocomplete-search","azure-app-service","blazor","data-indexing","dotnet","faceted-search","filtered-search","fuzzy-matching","fuzzy-search","indexing","information-retrieval","json-search","pattern-recognition","search","search-engine","search-library","search-server","search-service","structured-search"],"latest_commit_sha":null,"homepage":null,"language":"C#","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/indxSearch.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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-21T12:31:08.000Z","updated_at":"2026-01-08T08:17:32.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/indxSearch/IndxCloudApi","commit_stats":null,"previous_names":["indxsearch/indxcloudapi"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/indxSearch/IndxCloudApi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/indxSearch%2FIndxCloudApi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/indxSearch%2FIndxCloudApi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/indxSearch%2FIndxCloudApi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/indxSearch%2FIndxCloudApi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/indxSearch","download_url":"https://codeload.github.com/indxSearch/IndxCloudApi/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/indxSearch%2FIndxCloudApi/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28618348,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-20T22:24:05.405Z","status":"ssl_error","status_checked_at":"2026-01-20T22:20:31.342Z","response_time":117,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["asp-net","autocomplete-search","azure-app-service","blazor","data-indexing","dotnet","faceted-search","filtered-search","fuzzy-matching","fuzzy-search","indexing","information-retrieval","json-search","pattern-recognition","search","search-engine","search-library","search-server","search-service","structured-search"],"created_at":"2026-01-20T23:03:02.843Z","updated_at":"2026-01-20T23:03:22.576Z","avatar_url":"https://github.com/indxSearch.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Indx Cloud API\n\nA **ready-to-run** starter template for building a search service with **Indx Search**.\n\nThis template provides a complete Blazor Server application with HTTP API, user authentication, and everything you need to deploy a multi-user search service. Try it first, configure it later.\n\n## What's Included\n\n**Core Features:**\n- Blazor Server UI with interactive web interface\n- HTTP API with JWT authentication\n- User management and authentication (local accounts + OAuth)\n- API key generation for programmatic access\n- SQLite databases (ready for production alternatives)\n- Swagger documentation\n\n**Authentication:**\n- Local accounts (username/password) - works immediately\n- Microsoft OAuth (Azure AD) - optional\n- Google OAuth - optional\n- Password reset via email - works via console logging (optional SMTP)\n\n**Developer Experience:**\n- Works out of the box with minimal configuration\n- User Secrets for local development\n- Environment variables for production\n- Comprehensive setup guides\n\n## Quick Start\n\n### Prerequisites\n\n- [.NET 9.0 SDK](https://dotnet.microsoft.com/download/dotnet/9.0)\n- A code editor (VS Code, Visual Studio, Rider)\n\n### Get Running in 2 Steps\n This template works immediately without any secrets or external services.\n\n1. **Clone and run**\n   ```bash\n   git clone https://github.com/indxSearch/IndxCloudApi\n   cd IndxCloudApi\n   dotnet run\n   ```\n\n2. **Open your browser**\n   - Navigate to `https://localhost:5001`\n   - Register an account at `/Account/Register`\n   - Start using the search API\n\n**That's it.** The template works out-of-the-box with:\n- ✓ Local user accounts (username/password)\n- ✓ SQLite databases (auto-created in `./IndxData/`)\n- ✓ Console email mode (emails logged to console, no SMTP needed)\n- ✓ Default JWT configuration (secure for testing, customize for production)\n\n## Related Projects\n\n**IndxCloudApi** is part of the Indx Search ecosystem. These companion tools make it even easier to work with:\n\n### **Data Loaders** (C# / Node.js)\nCommand-line tools for loading data into your IndxCloudApi instance. Perfect for batch importing documents, testing with sample data, or automating dataset creation. Available in both C# and Node.js versions.\n\n- **IndxCloudLoader (C#):** [Repository](https://github.com/indxSearch/IndxCloudLoader)\n- **IndxNodeLoader (Node.js):** [Repository](https://github.com/indxSearch/IndxNodeLoader)\n- **Use cases:**\n  - Bulk load JSON documents\n  - Automated dataset setup for testing\n\n### **indx-intrface** (React)\nReady-to-use React UI components and a complete demo application for building search interfaces that connect to IndxCloudApi.\n\n- **Repository:** [indx-intrface](https://github.com/indxSearch/indx-intrface)\n- **Features:**\n  - Pre-built search components\n  - Working demo application\n  - Easy integration with your React projects\n\n### Testing Email Features (Console Mode)\n\nWhen testing password reset or other email features, check your console output. All emails are logged there:\n\n```\n========================================\nEMAIL SENT\nTo: user@example.com\nSubject: Reset your password\nBody:\nPlease reset your password by clicking here: \u003ca href='https://localhost:5001/Account/ResetPassword?code=...'\u003elink\u003c/a\u003e\n========================================\n```\n\nYou can copy the reset link directly from the console and paste it into your browser.\n\n## Project Structure\n\n```\nIndxCloudApi/\n├── Components/\n│   └── Account/          # Authentication \u0026 account management pages\n├── Controllers/          # HTTP API controllers (search, login)\n├── Data/                 # Database context and models\n├── Services/             # Email services (Console, Azure Communication)\n├── Shared/               # Layout and shared UI components\n├── docs/                 # Detailed setup guides\n└── IndxData/             # SQLite databases (identity.db, indx.db)\n```\n\n## Configuration\n\n**The template works without any configuration.** All settings below are optional and can be configured when you're ready for production or want additional features.\n\n### What Works Without Configuration\n\n- ✓ **User Registration \u0026 Login** - Local accounts with username/password\n- ✓ **JWT API Authentication** - Uses default key (will show warning on startup)\n- ✓ **Email Notifications** - Logged to console (perfect for testing)\n- ✓ **Password Reset** - Works via console emails\n- ✓ **API Key Generation** - Full JWT token management\n\n### Optional Configuration (When You're Ready)\n\n#### 1. Production JWT Key (Recommended for Production)\n\n```bash\n# Set a custom JWT key for production security\ndotnet user-secrets set \"Jwt:Key\" \"your-secret-key-minimum-32-characters-here\"\n```\n\n#### 2. OAuth Providers (Optional - Social Login)\n\nEnable Microsoft or Google authentication:\n\n```bash\n# Microsoft OAuth\ndotnet user-secrets set \"Authentication:Microsoft:ClientId\" \"your-client-id\"\ndotnet user-secrets set \"Authentication:Microsoft:ClientSecret\" \"your-client-secret\"\n\n# Google OAuth\ndotnet user-secrets set \"Authentication:Google:ClientId\" \"your-client-id\"\ndotnet user-secrets set \"Authentication:Google:ClientSecret\" \"your-client-secret\"\n```\n\nSee detailed guide: [OAuth Setup](docs/OAUTH_SETUP.md)\n\n#### 3. Production Email Service (Optional - Real Emails)\n\nConfigure Azure Communication Services for sending real emails:\n\n```bash\ndotnet user-secrets set \"Email:Provider\" \"AzureCommunicationServices\"\ndotnet user-secrets set \"Email:AzureCommunicationServices:ConnectionString\" \"your-connection-string\"\n```\n\nSee detailed guide: [Email Setup](docs/EMAIL_SETUP.md)\n\n### Production (Environment Variables)\n\nUse environment variables with double underscores for nested configuration:\n\n```bash\nexport Jwt__Key=\"your-secret-key-minimum-32-characters\"\nexport Authentication__Microsoft__ClientId=\"your-client-id\"\nexport Authentication__Microsoft__ClientSecret=\"your-client-secret\"\nexport Email__Provider=\"AzureCommunicationServices\"\n```\n\n## License Configuration\n\n**Indx Search** is completely free but includes a **100,000 document limit** by default. To remove this limit, you need to register as a developer.\n\n### Document Limits\n\n- **No License**: 100,000 documents maximum\n- **Extended License (Free)**: Removes limitation - requires registered account at indx.co\n- **Company License (Paid)**: Same capacity as extended license, but includes SLA and support\n\n### Getting a License\n\n**Option 1: Free Extended License (Recommended)**\n- Register an account at [https://indx.co](https://indx.co)\n- Request your free extended license - no restrictions\n- Use for any purpose: development, testing, or production\n- Filename: `indx-developer.license`\n\n**Option 2: Paid Company License**\n- For organizations requiring SLA and technical support\n- Includes service level guarantees and priority support\n- Same document capacity as extended license\n- Contact [https://indx.co](https://indx.co) for pricing\n- Filename: `indx-yourcompany.license` (e.g., `indx-google.license`, `indx-apple.license`)\n\n### License File Placement\n\nThe system automatically detects license files in the `./IndxData/` directory:\n\n```bash\nIndxCloudApi/\n└── IndxData/\n    ├── identity.db\n    ├── indx.db\n    └── indx-developer.license    # Place your license file here\n```\n\n**Steps:**\n1. Receive your license file (`.license` extension)\n2. Place it in `./IndxData/` directory\n3. Restart the application\n\nThe system will automatically detect and use any `.license` file in this directory. If multiple license files exist, it prioritizes `indx-company.license` over `indx-developer.license`.\n\n### Custom License Path (Optional)\n\nIf you need to store your license file elsewhere, configure the path in `appsettings.json`:\n\n```json\n{\n  \"Indx\": {\n    \"LicenseFile\": \"/path/to/your/license.file\"\n  }\n}\n```\n\nOr use environment variables for production:\n\n```bash\n# Local development (User Secrets)\ndotnet user-secrets set \"Indx:LicenseFile\" \"/path/to/license.file\"\n\n# Production (Environment Variable)\nexport Indx__LicenseFile=\"/path/to/license.file\"\n\n# Azure App Service (Application Settings)\nIndx__LicenseFile = \"/path/to/license.file\"\n```\n\n### Verifying Your License\n\nWhen the application starts, it logs the license status:\n\n```\n✓ Search system initialized at: ./IndxData/indx.db\n✓ Using license file: ./IndxData/indx-developer.license\n```\n\nOr if no license is found:\n\n```\nℹ No license file found - running with 100,000 document limit\n  Place your license file (.license) in ./IndxData/ to remove the limit\n```\n\n### Azure Deployment\n\n**For Azure App Service**, license files work the same way:\n\n1. **Option A: Include in deployment (Recommended)**\n   - Place license file in `./IndxData/` before publishing\n   - Deploy normally - the file will be included\n   - License file deploys with your application\n\n2. **Option B: Upload after deployment**\n   - Use FTP or Azure Portal App Service Editor (Kudu)\n   - Upload to `D:\\home\\site\\wwwroot\\IndxData\\`\n   - Useful if you need to update the license without redeploying\n\n**Important**: The `./IndxData/` directory persists across restarts on Azure App Service. License files placed there remain available even after redeployment.\n\n## Using the API\n\n### Web UI Access\n\n1. Register: `/Account/Register`\n2. Login: `/Account/Login`\n3. Manage account: `/Account/Manage`\n\n### API Access\n\n1. **Generate an API key:**\n   - Login to the web UI\n   - Navigate to **API Key** in the menu\n   - Generate a JWT token (30/90/180/365 days)\n\n2. **Use the token:**\n   ```bash\n   curl -H \"Authorization: Bearer \u003cyour-token\u003e\" https://localhost:5001/api/search\n   ```\n\n3. **API Documentation:**\n   - Swagger UI: `https://localhost:5001/swagger`\n   - Interactive testing and full endpoint documentation\n\n## Database\n\n**SQLite:**\n- `./IndxData/identity.db` - User accounts and authentication through ASP.NET Core Identity\n- `./IndxData/indx.db` - Application configuration and JSON data\n\n**Important:** Indx Search keeps all search indexes in memory for performance. The `indx.db` file is used for configuration and metadata only, not for storing search data.\n\n**Migrations:**\n```bash\n# Create a migration for identity database\ndotnet ef migrations add MigrationName\n\n# Apply migrations\ndotnet ef database update\n```\n\n**Production:** For identity storage, SQLite works well for moderate loads. For high-traffic scenarios, configure SQL Server, PostgreSQL, or MySQL by updating the connection string in `Program.cs`.\n\n## Security\n\n**Default Configuration (Development/Testing):**\n- ✓ Safe for local development and testing\n- ✓ Uses a default JWT key (you'll see a warning on startup)\n- ✓ No secrets exposed in git\n- ✓ HTTPS enabled by default\n- ✓ Open registration (anyone can create an account)\n\n**Password Requirements:**\n- Minimum 8 characters\n- Uppercase, lowercase, digit, and special character required\n\n**JWT Tokens:**\n- Configurable expiration (30-365 days)\n- Default key is secure for testing, but should be customized for production\n\n### Restricting Registration\n\nBy default, **anyone can register** for ease of getting started. You can easily restrict who can register by configuring the registration mode.\n\n**Note:** Registration restrictions apply to **all registration methods** including local accounts (username/password) and OAuth providers (Google/Microsoft). OAuth users cannot bypass domain restrictions.\n\n#### Open Registration (Default)\n```json\n{\n  \"Registration\": {\n    \"Mode\": \"Open\"\n  }\n}\n```\nAnyone can create an account - perfect for getting started or public APIs.\n\n#### Restrict by Email Domain\n```json\n{\n  \"Registration\": {\n    \"Mode\": \"EmailDomain\",\n    \"AllowedDomains\": [\"yourcompany.com\", \"partner.com\"]\n  }\n}\n```\nOnly users with email addresses from specified domains can register - great for organization-specific APIs.\n\n#### Close Registration\n```json\n{\n  \"Registration\": {\n    \"Mode\": \"Closed\"\n  }\n}\n```\nNo one can self-register. Only admins can create accounts - ideal for private APIs with known users.\n\n#### Using Environment Variables (Production)\n```bash\n# Azure App Service Application Settings\nRegistration__Mode = \"EmailDomain\"\nRegistration__AllowedDomains__0 = \"yourcompany.com\"\nRegistration__AllowedDomains__1 = \"partner.com\"\n\n# Or for closed registration\nRegistration__Mode = \"Closed\"\n```\n\nThe registration page will automatically show appropriate messages to users based on your configuration.\n\n### Requiring Email Confirmation\n\nBy default, users can sign in immediately after registration. You can require email confirmation before users can sign in:\n\n```json\n{\n  \"Identity\": {\n    \"RequireConfirmedEmail\": true\n  }\n}\n```\n\n**How it works:**\n- Users must click the confirmation link sent to their email before they can sign in\n- OAuth users (Google/Microsoft) are **automatically confirmed** since their email is already verified by the provider\n- Confirmation emails are sent using your configured email provider (Console, Azure Communication Services, etc.)\n- With Console email provider (default), check the console output for the confirmation link\n\n**Using Environment Variables (Production):**\n```bash\n# Azure App Service Application Settings\nIdentity__RequireConfirmedEmail = \"true\"\n```\n\n**Production Best Practices:**\n- Change the JWT key (see Configuration section above)\n- Configure registration restrictions based on your use case\n- Never commit secrets to git\n- Use User Secrets for development\n- Use Azure Key Vault or environment variables for production\n- Enable HTTPS (included by default)\n- Rotate secrets regularly\n\n## Deployment\n\n### Azure App Service (Zero Configuration!)\n\n**This template works on Azure without any configuration!** Just deploy and run.\n\n#### Deploy Steps:\n\n1. **Create App Service** in Azure Portal\n   - Choose **.NET 9** runtime\n   - Any tier (Free F1 works for testing)\n\n2. **Configure Environment** (Important!)\n   - Go to **Configuration → General settings**\n   - Set **Stack**: .NET\n   - Set **Major version**: .NET 9\n   - Set **ASPNETCORE_ENVIRONMENT** = `Production` (uses appsettings.production.json)\n\n3. **Deploy**\n   ```bash\n   # Using Azure CLI\n   az webapp up --name your-app-name --resource-group your-resource-group\n\n   # Or publish and deploy\n   dotnet publish -c Release\n   # Then deploy using Azure Portal, VS Code, or GitHub Actions\n   ```\n\nThat's it! The app will use:\n- ✓ SQLite databases in Azure's persistent storage (`D:\\home\\data\\`)\n- ✓ Default JWT key (with warning message)\n- ✓ Console email logging (visible in Log Stream)\n- ✓ No Application Settings required!\n\n#### Optional: Production Configuration\n\nOnce deployed, you can optionally configure:\n\n**Application Settings** (Environment variables → App settings or Configuration → Application settings):\n```\nJwt__Key = \"your-custom-production-key-32-characters-minimum\"\nAuthentication__Microsoft__ClientId = \"your-client-id\"\nAuthentication__Microsoft__ClientSecret = \"your-client-secret\"\nEmail__Provider = \"AzureCommunicationServices\"\nEmail__AzureCommunicationServices__ConnectionString = \"your-acs-connection\"\nRegistration__Mode = \"EmailDomain\"\nRegistration__AllowedDomains__0 = \"yourcompany.com\"\nRegistration__AllowedDomains__1 = \"partner.com\"\n```\n\n**Note:** In the Azure Portal, these settings may be found under:\n- **\"Environment variables\"** → **\"App settings\"** (newer portal UI), OR\n- **\"Configuration\"** → **\"Application settings\"** (classic portal UI)\n\nClick **\"+ Add\"** to add each setting. Azure will automatically restart your app when you save changes.\n\n**Remember**: If adding OAuth, update redirect URIs in Azure AD to include:\n- `https://your-app.azurewebsites.net/signin-microsoft`\n- `https://your-app.azurewebsites.net/signin-google`\n\n## Development Commands\n\n```bash\n# Build the project\ndotnet build\n\n# Run with auto-reload\ndotnet watch run\n\n# Run tests\ndotnet test\n\n# View user secrets\ndotnet user-secrets list\n```\n\n## Customization\n\nThis is a **starter template** - customize it for your needs:\n\n1. **Add your search implementation** in `Controllers/SearchController.cs`\n2. **Customize the UI** in `Components/` and `Shared/`\n3. **Add more API endpoints** in `Controllers/`\n4. **Change database** by updating connection strings in `Program.cs`\n5. **Add email provider** by implementing `IEmailSender` in `Services/`\n\n## Dependencies\n\n- **IndxSearchLib** (4.1.0) - Core search functionality\n- ASP.NET Core 9.0 - Web framework\n- Entity Framework Core - Database ORM\n- Swashbuckle - API documentation\n- Azure Communication Services - Email (optional)\n\n## Support\n\n- Check the [setup guides](docs/) for detailed configuration\n- Review [Swagger documentation](https://localhost:5001/swagger) for API reference\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Findxsearch%2Findxcloudapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Findxsearch%2Findxcloudapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Findxsearch%2Findxcloudapi/lists"}