diff --git a/.gitignore b/.gitignore index a862462..4eadd2a 100644 --- a/.gitignore +++ b/.gitignore @@ -44,3 +44,6 @@ public/assets/ # Playwright test results test-results/ .last-run.json + +# Temporary files +tmp/ diff --git a/README.md b/README.md index 6ae43fe..7f6c47e 100644 --- a/README.md +++ b/README.md @@ -49,62 +49,16 @@ Check out our [GitHub Project](https://github.com/users/chrisvel/projects/2) for ## 🛠️ Getting Started -### Quick Start with Docker - -**One simple command**, that's all it takes to run tududi with Docker. - -First pull the latest image: +Get up and running quickly with our comprehensive documentation: +### Quick Start ```bash docker pull chrisvel/tududi:latest -``` -### ⚙️ Environment Variables - -The following environment variables are used to configure tududi: - -#### Required Variables: -- `TUDUDI_USER_EMAIL` - Initial admin user's email address (e.g., `admin@example.com`) -- `TUDUDI_USER_PASSWORD` - Initial admin user's password (use a strong password!) -- `TUDUDI_SESSION_SECRET` - Session encryption key (generate with `openssl rand -hex 64`) - -#### Optional Variables: -- `PUID`, `GUID` - Run with specified user and group ID (instead of defaults 1001/1001) -- `DB_FILE` - Path to sqlite DB file -- `TUDUDI_UPLOAD_PATH` - Path where uploaded files are stored -- `TUDUDI_ALLOWED_ORIGINS` - Controls CORS access for different deployment scenarios: - - Not set: Only allows localhost origins - - Specific domains: `https://tududi.com,http://localhost:3002` - - Allow all (development only): Set to empty string `""` - -#### Common Configuration Examples: - -##### Local Development -```bash -export TUDUDI_USER_EMAIL=dev@local.test -export TUDUDI_USER_PASSWORD=devpassword123 -export TUDUDI_SESSION_SECRET=$(openssl rand -hex 64) -# TUDUDI_ALLOWED_ORIGINS not set - defaults to localhost only -``` - -##### Production with Reverse Proxy -```bash -export TUDUDI_USER_EMAIL=admin@yourdomain.com -export TUDUDI_USER_PASSWORD=your-secure-password-here -export TUDUDI_SESSION_SECRET=$(openssl rand -hex 64) -export TUDUDI_ALLOWED_ORIGINS=https://tududi.yourdomain.com -``` - -### 🚀 Running with Docker - -```bash docker run \ - -e TUDUDI_USER_EMAIL=myemail@example.com \ - -e TUDUDI_USER_PASSWORD=mysecurepassword \ + -e TUDUDI_USER_EMAIL=admin@example.com \ + -e TUDUDI_USER_PASSWORD=your-secure-password \ -e TUDUDI_SESSION_SECRET=$(openssl rand -hex 64) \ - -e TUDUDI_ALLOWED_ORIGINS=https://tududi,http://tududi:3002 \ - -e PUID=1001 \ - -e GUID=1001 \ -v ~/tududi_db:/app/backend/db \ -v ~/tududi_uploads:/app/backend/uploads \ -p 3002:3002 \ @@ -113,266 +67,57 @@ docker run \ Navigate to [http://localhost:3002](http://localhost:3002) and login with your credentials. -## 📱 Telegram Integration Setup +### 📚 Documentation -tududi includes built-in Telegram integration that allows you to create tasks directly from Telegram messages. This feature is optional and can be configured after installation. +For detailed setup instructions, configuration options, and getting started guides, visit: -### 🤖 Creating a Telegram Bot +**[docs.tududi.com](https://docs.tududi.com)** -1. **Start a chat with @BotFather** on Telegram -2. **Create a new bot**: - ``` - /newbot - ``` -3. **Choose a name** for your bot (e.g., "My tududi Bot") -4. **Choose a username** for your bot (must end with "bot", e.g., "mytududi_bot") -5. **Save the bot token** - BotFather will provide a token like `123456789:ABCdefGHIjklMNOpqrSTUvwxyz` +- **[Installation Guide](https://docs.tududi.com/installation)** - Docker, development setup, and deployment +- **[Configuration](https://docs.tududi.com/configuration)** - Environment variables and advanced settings +- **[First Steps](https://docs.tududi.com/first-steps)** - Learn the basics and get productive +- **[Project Sharing](https://docs.tududi.com/project-sharing)** - Collaborate with your team -### ⚙️ Configuring Telegram Integration +## 📱 Telegram Integration -#### Method: Through the Web Interface (Recommended) +Tududi includes built-in Telegram integration that allows you to create tasks directly from Telegram messages. This feature is optional and can be configured after installation through the web interface. -1. **Login to tududi** and go to Settings -2. **Navigate to the Telegram tab** -3. **Paste your bot token** from BotFather -4. **Click "Setup Telegram"** - this will: - - Validate your bot token - - Display your bot's username - - Provide a direct link to start chatting with your bot -5. **Start chatting** with your bot by clicking the provided link or searching for your bot in Telegram -6. **Send your first message** to your bot - it will automatically appear in your tududi inbox! - -### 🔄 How It Works - -1. **Message Collection**: tududi polls your bot every 30 seconds for new messages -2. **Automatic Inbox Creation**: Every message sent to your bot creates a new item in your tududi inbox -3. **Duplicate Prevention**: The same message won't create multiple inbox items -4. **Processing**: You can then process inbox items into tasks, projects, or notes - -### 📊 Telegram Settings Overview - -In the Telegram settings tab, you can: - -- **Bot Setup**: Configure your bot token and view connection status -- **Polling Control**: Start/stop message polling manually -- **Bot Information**: View bot username and connection status -- **Test Integration**: Send a test message to verify connectivity -- **Task Summaries**: Enable/disable daily task summary notifications - -### 🔧 Troubleshooting - -**Bot not receiving messages:** -- Verify your bot token is correct -- Ensure you've started a conversation with your bot in Telegram -- Check that polling is active in the Telegram settings -- Verify your server can reach Telegram's API (check firewall settings) - -**Messages not appearing in inbox:** -- Check the polling status in Telegram settings -- Verify your bot token hasn't expired -- Ensure your account is properly connected to the bot - -**Bot setup failing:** -- Double-check your bot token format (should be like `123456789:ABCdefGHIjklMNOpqrSTUvwxyz`) -- Verify your bot is active and not deleted -- Check your internet connection - -### 🔒 Security Considerations - -- **Bot tokens are stored securely** in your local database -- **Only you can send messages** to your bot (private by default) -- **No data is shared** with third parties - everything runs on your self-hosted instance -- **Tokens are encrypted** in transit and at rest - -### 🚫 Disabling Telegram Integration - -To completely disable Telegram integration: - -1. **Via Interface**: Simply don't configure a bot token in the settings -2. **Remove Bot Token**: Delete your bot token from the Telegram settings to stop all integration - -### 🔑 Authentication - -The application uses session-based authentication with secure cookies. For development: -- Frontend runs on port 8080 with webpack dev server -- Backend runs on port 3001 and handles authentication -- CORS is configured to allow cross-origin requests during development -- In production (Docker), both frontend and backend run on the same port (3002) +For detailed setup instructions, see the **[Telegram Integration Guide](https://docs.tududi.com/telegram)** at [docs.tududi.com](https://docs.tududi.com) ## 🚧 Development -### Prerequisites +Want to contribute or run Tududi from source? Check out our comprehensive development guide: -Before you begin, ensure you have the following installed: -- Node.js (version 20 or higher) -- Express.js -- SQLite3 -- npm -- ReactJS - -### 🏗 Installation - -To install `tududi`, follow these steps: - -1. Clone the repository: - ```bash - git clone https://github.com/chrisvel/tududi.git - ``` -2. Navigate to the project directory: - ```bash - cd tududi - ``` -3. Install the required dependencies: - ```bash - # Install all dependencies (frontend and backend) - npm install - ``` - -### 📂 Database Setup - -The database will be automatically initialized when you start the Express backend. For manual database operations: +**[Development Setup Guide](https://docs.tududi.com/installation#development-installation)** +Quick overview: ```bash -# Initialize database (creates tables, drops existing data) -npm run db:init +# Clone and install +git clone https://github.com/chrisvel/tududi.git +cd tududi +npm install -# Sync database (creates tables if they don't exist) -npm run db:sync - -# Migrate database (alters existing tables to match models) -npm run db:migrate - -# Reset database (drops and recreates all tables) -npm run db:reset - -# Check database status and connection -npm run db:status +# Start development servers +npm run backend:dev # Terminal 1 - Backend on :3001 +npm run frontend:dev # Terminal 2 - Frontend on :8080 ``` -### 🔄 Database Migrations - -For schema changes, use Sequelize migrations (similar to Rails/Ruby migrations): - -```bash -# Create a new migration -npm run migration:create add-description-to-tasks - -# Run pending migrations -npm run migration:run - -# Check migration status -npm run migration:status - -# Rollback last migration -npm run migration:undo - -# Rollback all migrations -npm run migration:undo:all -``` - -#### Creating a New Migration Example: -```bash -# 1. Create the migration file -npm run migration:create add-priority-to-projects - -# 2. Edit the generated file in migrations/ folder: -# - Add your schema changes in the 'up' function -# - Add rollback logic in the 'down' function - -# 3. Run the migration -npm run migration:run -``` - -### 👤 User Setup - -#### For Development - -Set environment variables to automatically create the initial user: - -```bash -export TUDUDI_USER_EMAIL=dev@example.com -export TUDUDI_USER_PASSWORD=password123 -export TUDUDI_SESSION_SECRET=$(openssl rand -hex 64) -``` - -Or create a user manually: -```bash -npm run user:create dev@example.com password123 -``` - -#### Default Development Credentials - -If no environment variables are set, you can use the default development credentials: -- Email: `dev@example.com` -- Password: `password123` - -### 🚀 Usage - -To start the application for development: - -1. **Start the Express backend** (in one terminal): - ```bash - npm run backend:dev # Development mode with auto-reload - # Or: npm run backend:start # Production mode - ``` - The backend will run on `http://localhost:3001` - -2. **Start the frontend development server** (in another terminal): - ```bash - npm run frontend:dev - ``` - The frontend will run on `http://localhost:8080` - -3. **Access the application**: Open your browser to `http://localhost:8080` - -### Port Configuration - -- **Development Frontend**: `http://localhost:8080` (webpack dev server) -- **Development Backend**: `http://localhost:3001` (Express API server) -- **Docker/Production**: `http://localhost:3002` (combined frontend + backend) - -The webpack dev server automatically proxies API calls and locales to the backend server. - -### 🔍 Testing - -To run tests: - -```bash -# Backend tests -npm run backend:test - -# Frontend tests -npm run frontend:test -``` - -#### Test Coverage - -The application includes comprehensive test coverage for: -- **Backend API endpoints** (tasks, projects, areas, notes, tags, auth) -- **Database models and migrations** -- **Recurring task service and date calculations** -- **Frontend components and utilities** -- **Authentication and session management** - -**Note**: Comprehensive test coverage for the new recurring tasks functionality is planned and will include: -- Recurring task generation algorithms -- Parent-child relationship management -- Date calculation edge cases -- Frontend recurring task components -- Integration tests for complete recurring task workflows - -The application has been fully migrated from Ruby/Sinatra to a functional programming Express.js implementation. +For database management, testing, and detailed development instructions, see [docs.tududi.com](https://docs.tududi.com) ## 🤝 Contributing -Contributions to `tududi` are welcome. To contribute: +Contributions to Tududi are welcome! Whether it's bug fixes, new features, documentation improvements, or translations, we appreciate your help. -1. Fork the repository. -2. Create a new branch (\`git checkout -b feature/AmazingFeature\`). -3. Make your changes. -4. Commit your changes (\`git commit -m 'Add some AmazingFeature'\`). -5. Push to the branch (\`git push origin fexature/AmazingFeature\`). -6. Open a pull request. +**Quick Start:** +1. Fork the repository +2. Create a feature branch (`git checkout -b feature/AmazingFeature`) +3. Make your changes +4. Run tests (`npm run backend:test && npm run frontend:test`) +5. Commit your changes (`git commit -m 'Add some AmazingFeature'`) +6. Push to your fork (`git push origin feature/AmazingFeature`) +7. Open a Pull Request + +For detailed contribution guidelines, development setup, and coding standards, see [docs.tududi.com/contributing](https://docs.tududi.com/contributing) ## 📜 License