{"id":26833058,"url":"https://github.com/meownowapp/meownow","last_synced_at":"2025-03-30T15:26:49.492Z","repository":{"id":267189071,"uuid":"900495641","full_name":"MeowNowApp/MeowNow","owner":"MeowNowApp","description":"🐱 Random cat photos at the press of a button! Upload your own cat pics \u0026 discover others. Built with AWS serverless for purr-formance.","archived":false,"fork":false,"pushed_at":"2025-03-30T00:52:10.000Z","size":161,"stargazers_count":0,"open_issues_count":3,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-30T01:23:43.050Z","etag":null,"topics":["aws","aws-lambda","aws-s3","css","docker","dockerfile","html","javascript","js","php","serverless","webserver","website"],"latest_commit_sha":null,"homepage":"https://meownow.app","language":"PHP","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/MeowNowApp.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":"2024-12-08T22:48:42.000Z","updated_at":"2025-03-30T00:36:41.000Z","dependencies_parsed_at":null,"dependency_job_id":"24a79678-7b8b-4387-b5dc-fd53e2dc60f3","html_url":"https://github.com/MeowNowApp/MeowNow","commit_stats":null,"previous_names":["wbreiler/randomcat","wbreiler/meownow","meownowapp/meownow"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MeowNowApp%2FMeowNow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MeowNowApp%2FMeowNow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MeowNowApp%2FMeowNow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MeowNowApp%2FMeowNow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MeowNowApp","download_url":"https://codeload.github.com/MeowNowApp/MeowNow/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246337028,"owners_count":20761141,"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":["aws","aws-lambda","aws-s3","css","docker","dockerfile","html","javascript","js","php","serverless","webserver","website"],"created_at":"2025-03-30T15:26:48.405Z","updated_at":"2025-03-30T15:26:49.486Z","avatar_url":"https://github.com/MeowNowApp.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MeowNow 😸\n\nA simple and elegant web application for displaying and sharing random cat images using AWS S3 for storage.\n\n## Features\n\n- **Random Cat Display**: Shows random cat images from your S3 bucket\n- **Simple Interface**: Clean, responsive design that works on all devices\n- **Image Upload**: Users can upload their own cat photos directly to S3\n- **On-the-fly Compression**: Uses AWS Lambda to compress images when they're accessed\n- **EXIF Orientation Fix**: Automatically corrects image orientation based on EXIF data\n- **Keyboard Shortcuts**: Press spacebar to show another cat\n- **Fallback CSS**: Multiple layers of CSS fallback to ensure the site always looks good\n- **Cloud Storage**: Uses AWS S3 for reliable, scalable image storage\n- **Public API**: Access random cat images programmatically via API\n\n## Project Structure\n\n```\nmeownow/\n├── config/           # Configuration files\n│   ├── .env         # Environment variables (not in repo)\n│   └── config.php   # PHP configuration\n├── docker/          # Docker configuration\n│   ├── config/      # Docker-specific config\n│   ├── scripts/     # Docker scripts\n│   └── Dockerfile   # Main Dockerfile\n├── docs/           # Documentation\n│   ├── api-docs.md\n│   ├── privacypolicy.md\n│   └── LICENSE\n├── public/         # Public web root\n│   ├── api/       # API endpoints\n│   ├── css/       # Stylesheets\n│   ├── js/        # JavaScript files\n│   └── images/    # Static images\n├── src/           # Source code\n│   ├── api/       # API implementation\n│   └── utils/     # Utility functions\n└── vendor/        # Composer dependencies\n```\n\n## Setup\n\n1. Clone the repository:\n   ```bash\n   git clone https://github.com/yourusername/meownow.git\n   cd meownow\n   ```\n\n2. Copy the environment file:\n   ```bash\n   cp config/.env.example config/.env\n   ```\n\n3. Edit `config/.env` with your AWS credentials and configuration.\n\n4. Install dependencies:\n   ```bash\n   composer install\n   ```\n\n5. Build and start Docker container:\n   ```bash\n   docker-compose up -d\n   ```\n\n6. Access the website at http://localhost:8080\n\n## API Documentation\n\nThe API documentation is available at:\n- [Web Version](http://localhost:8080/api-docs.html)\n- [Markdown Version](docs/api-docs.md)\n\n### Basic Usage\n\n```bash\n# Get a random cat image (redirects to the image URL)\ncurl https://meownow.app/api/v1/random\n\n# Get JSON metadata about a random cat image\ncurl https://meownow.app/api/v1/random?format=json\n\n# Get just the URL as plain text\ncurl https://meownow.app/api/v1/random?format=url\n\n# Download the image directly\ncurl -o cat.jpg https://meownow.app/api/v1/random?format=image\n```\n\n### Using in HTML\n\n```html\n\u003cimg src=\"https://meownow.app/api/v1/random\" alt=\"Random Cat\"\u003e\n```\n\n## Development\n\n### Prerequisites\n\n- PHP 8.0 or higher\n- Composer\n- Docker and Docker Compose\n- AWS account with S3 access\n\n### Local Development\n\n1. Clone the repository\n2. Copy and configure `.env`\n3. Install dependencies\n4. Run `docker-compose up -d`\n\n### Testing\n\n```bash\ncomposer test\n```\n\n## License\n\nSee [LICENSE](docs/LICENSE) for details.\n\n## Credits\n\nCreated by [wbreiler.com](https://wbreiler.com)\n\n## AWS Architecture\n\n### S3 Storage\n\nThe application uses a two-bucket approach for image storage:\n\n- **Raw Bucket (meownowraw)**: Stores original, unprocessed images uploaded by users\n- **Compressed Bucket (meownowcompressed)**: Stores processed, optimized images for display\n\n### Lambda Image Processing\n\nThe application uses AWS Lambda for on-the-fly image compression and processing:\n\n1. Original images are uploaded directly to the raw S3 bucket\n2. When an image is requested, a Lambda function is triggered\n3. The Lambda function retrieves the original image from the raw bucket, compresses it, and saves it to the compressed bucket\n4. The web application serves images from the compressed bucket\n5. Processed images are cached in the compressed bucket for improved performance\n\nThis serverless approach eliminates the need for server-side compression during upload and allows for dynamic resizing and optimization based on the requesting device.\n\n## Environment Variables\n\nThis application uses environment variables for configuration. For security reasons, details about specific variables are not documented here. Refer to the `.env.example` file for the required configuration.\n\n## Directory Structure\n\n- `index.html` - Main page that displays random cat images\n- `script.js` - JavaScript for fetching and displaying cat images\n- `style.css` - Main stylesheet\n- `backup.css` - Fallback stylesheet if the main one fails to load\n- `upload.php` - Handles image uploads to S3\n- `list.php` - Returns a JSON list of available cat images from S3\n- `cat_list.json` - Local cache of uploaded images (fallback for S3)\n- `logs/` - Directory for log files\n- `vendor/` - Directory for Composer dependencies (AWS SDK)\n\n## Image Upload\n\nThe application allows users to upload their own cat photos with the following features:\n\n- Supports JPG and PNG formats\n- Maximum file size: 50MB per file, 250MB total per upload session\n- EXIF orientation correction\n- Unique filename generation to prevent conflicts\n- Direct upload to S3 with public-read ACL\n\n## Browser Compatibility\n\nMeowNow works on all modern browsers including:\n\n- Google Chrome\n- Mozilla Firefox\n- Apple Safari\n- Microsoft Edge\n\n## Performance Optimizations\n\n- CSS and image preloading\n- Multiple CSS fallback mechanisms\n- Next image preloading for faster browsing\n- Cloud-based image storage for reliability and performance\n- Serverless image processing with AWS Lambda:\n  - On-demand compression reduces storage requirements\n  - Dynamic resizing based on client device capabilities\n  - Caching of processed images for faster subsequent access\n  - Reduced load on the web server by offloading image processing\n  - Automatic scaling to handle traffic spikes\n\n## Privacy Policy\n\nWe take user privacy seriously. Please review our [Privacy Policy](privacypolicy.md) for details on how we handle user data.\n\n## Docker Setup\n\nThis project includes a Docker setup for easy deployment and development.\n\n### Prerequisites\n\n- Docker\n- Docker Compose\n\n### Quick Start\n\n1. Copy the example environment file:\n   ```bash\n   cp docker/config/.env.example .env\n   ```\n\n2. Edit the `.env` file with your AWS credentials and configuration.\n\n3. Build and start the container:\n   ```bash\n   docker-compose up -d\n   ```\n\n4. Access the website at http://localhost:8080\n\n### Configuration\n\nAll Docker-related files are stored in the `./docker` directory:\n- `docker/Dockerfile`: Main Docker configuration\n- `docker/entrypoint.sh`: Container startup script\n- `docker/config/.env.example`: Example environment variables\n\n### Development\n\nFor development, you can uncomment the volume mounts in `docker-compose.yml` to override files in the container with your local files:\n\n```yaml\nvolumes:\n  - ./css:/var/www/html/css\n  - ./js:/var/www/html/js\n  - ./api:/var/www/html/api\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmeownowapp%2Fmeownow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmeownowapp%2Fmeownow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmeownowapp%2Fmeownow/lists"}