Andrey K. Choi
2e535513b5
+ Наведен порядок в файлах проекта + Наведен порядок в документации + Настроены скрипты установки, развертки и так далее, расширен MakeFile
411 lines
15 KiB
Markdown
411 lines
15 KiB
Markdown
# 🐱 CatLink - Персональные страницы ссылок# 🐱 CatLink - Персональные страницы ссылок
|
||
|
||
|
||
|
||
[](https://opensource.org/licenses/MIT)[](https://opensource.org/licenses/MIT)
|
||
|
||
[](https://docker.com)[](https://docker.com)
|
||
|
||
[](https://nextjs.org)[](https://nextjs.org)
|
||
|
||
[](https://djangoproject.com)[](https://djangoproject.com)
|
||
|
||
|
||
|
||
**CatLink** - современная платформа для создания красивых персональных страниц со всеми важными ссылками в одном месте. Альтернатива Linktree с открытым исходным кодом.**CatLink** - современная платформа для создания красивых персональных страниц со всеми важными ссылками в одном месте. Альтернатива Linktree с открытым исходным кодом.
|
||
|
||
|
||
|
||
## ✨ Возможности## ✨ Возможности
|
||
|
||
|
||
|
||
- 🎨 **Множество макетов**: список, сетка, компактная сетка, журнальная верстка- 🎨 **Множество макетов**: список, сетка, компактная сетка, журнальная верстка
|
||
|
||
- 🎭 **Персонализация**: настройка цветов, фонов, иконок- 🎭 **Персонализация**: настройка цветов, фонов, иконок
|
||
|
||
- 📱 **Адаптивный дизайн**: отлично работает на всех устройствах- 📱 **Адаптивный дизайн**: отлично работает на всех устройствах
|
||
|
||
- 🔐 **Система аутентификации**: регистрация и управление профилем- 🔐 **Система аутентификации**: регистрация и управление профилем
|
||
|
||
- 📊 **Группировка ссылок**: организация ссылок по категориям- 📊 **Группировка ссылок**: организация ссылок по категориям
|
||
|
||
- 🌐 **SEO-оптимизация**: дружественные URL и метатеги- 🌐 **SEO-оптимизация**: дружественные URL и метатеги
|
||
|
||
- 🚀 **Высокая производительность**: быстрая загрузка и отзывчивость- 🚀 **Высокая производительность**: быстрая загрузка и отзывчивость
|
||
|
||
- 🐳 **Docker Ready**: простой деплой с помощью контейнеров- 🐳 **Docker Ready**: простой деплой с помощью контейнеров
|
||
|
||
|
||
|
||
## 🚀 Быстрый старт## 🚀 Быстрый старт
|
||
|
||
|
||
|
||
### Требования### Требования
|
||
|
||
- Docker и Docker Compose- Docker и Docker Compose
|
||
|
||
- Make (для удобства)- Make (для удобства)
|
||
|
||
- Git- Git
|
||
|
||
|
||
|
||
### Установка### Установка
|
||
|
||
|
||
|
||
1. **Клонируйте репозиторий**1. **Клонируйте репозиторий**
|
||
|
||
```bash ```bash
|
||
|
||
git clone https://github.com/smartsoltech/links.git git clone https://github.com/smartsoltech/links.git
|
||
|
||
cd links cd links
|
||
|
||
``` ```
|
||
|
||
|
||
|
||
2. **Запустите установку**2. **Запустите установку**
|
||
|
||
```bash ```bash
|
||
|
||
make install make install
|
||
|
||
``` ```
|
||
|
||
|
||
|
||
3. **Откройте в браузере**3. **Откройте в браузере**
|
||
|
||
- Frontend: http://localhost:3000 - Frontend: http://localhost:3000
|
||
|
||
- Backend API: http://localhost:8000 - Backend API: http://localhost:8000
|
||
|
||
- Django Admin: http://localhost:8000/admin - Django Admin: http://localhost:8000/admin
|
||
|
||
|
||
|
||
### Альтернативная установка (без Make)### Альтернативная установка (без Make)
|
||
|
||
```bash```bash
|
||
|
||
# Копируйте пример конфигурации# Копируйте пример конфигурации
|
||
|
||
cp .env.example .envcp .env.example .env
|
||
|
||
|
||
|
||
# Отредактируйте .env файл# Отредактируйте .env файл
|
||
|
||
nano .envnano .env
|
||
|
||
|
||
|
||
# Запустите контейнеры# Запустите контейнеры
|
||
|
||
docker-compose up -d --builddocker-compose up -d --build
|
||
|
||
|
||
|
||
# Примените миграции# Примените миграции
|
||
|
||
docker-compose exec web python manage.py migratedocker-compose exec web python manage.py migrate
|
||
|
||
|
||
|
||
# Создайте суперпользователя# Создайте суперпользователя
|
||
|
||
docker-compose exec web python manage.py createsuperuserdocker-compose exec web python manage.py createsuperuser
|
||
|
||
``````
|
||
|
||
|
||
|
||
## 📋 Управление с помощью Make## 📋 Управление с помощью Make
|
||
|
||
|
||
|
||
Проект включает мощный Makefile для упрощения разработки:Проект включает мощный Makefile для упрощения разработки:
|
||
|
||
|
||
|
||
```bash```bash
|
||
|
||
make help # Показать все доступные командыmake help # Показать все доступные команды
|
||
|
||
make dev-bg # Запуск для разработки в фонеmake dev-bg # Запуск для разработки в фоне
|
||
|
||
make status # Проверить статус сервисовmake status # Проверить статус сервисов
|
||
|
||
make health # Проверить работоспособностьmake health # Проверить работоспособность
|
||
|
||
make logs # Просмотр логовmake logs # Просмотр логов
|
||
|
||
make migrate-full # Выполнить миграции и собрать статикуmake migrate-full # Выполнить миграции и собрать статику
|
||
|
||
make backup # Создать бэкап базы данныхmake backup # Создать бэкап базы данных
|
||
|
||
``````
|
||
|
||
|
||
|
||
📖 **[Полное руководство по Makefile](./docs/MAKEFILE.md)**📖 **[Полное руководство по Makefile](./docs/MAKEFILE.md)**
|
||
|
||
|
||
|
||
## 🏗️ Архитектура## 🏗️ Архитектура
|
||
|
||
|
||
|
||
### Технологический стек### Технологический стек
|
||
|
||
- **Frontend**: Next.js 15, React, TypeScript, Bootstrap 5
|
||
|
||
- **Backend**: Django 5.2, Django REST Framework**Backend:**
|
||
|
||
- **База данных**: PostgreSQL- Django 5.2 + Django REST Framework
|
||
|
||
- **Контейнеризация**: Docker, Docker Compose- PostgreSQL
|
||
|
||
- **Веб-сервер**: Nginx (для продакшена)- JWT Authentication
|
||
|
||
- Django CORS Headers
|
||
|
||
### Структура проекта- Gunicorn
|
||
|
||
```
|
||
|
||
catlink/**Frontend:**
|
||
|
||
├── frontend/linktree-frontend/ # Next.js приложение- Next.js 15.3.1
|
||
|
||
├── backend/ # Django API- React 19
|
||
|
||
├── scripts/ # Скрипты автоматизации- TypeScript
|
||
|
||
├── docs/ # Документация- Tailwind CSS
|
||
|
||
├── storage/ # Загруженные файлы- Axios для API запросов
|
||
|
||
├── docker-compose.yml # Конфигурация Docker
|
||
|
||
├── Makefile # Команды автоматизации## Быстрый старт
|
||
|
||
└── README.md # Этот файл
|
||
|
||
```### 1. Подготовка окружения
|
||
|
||
|
||
|
||
## 🎯 Использование```bash
|
||
|
||
# Клонируйте репозиторий
|
||
|
||
### Для пользователейgit clone <url>
|
||
|
||
cd links
|
||
|
||
1. **Регистрация**: Создайте аккаунт на главной странице
|
||
|
||
2. **Настройка профиля**: Загрузите аватар, укажите информацию# Скопируйте переменные окружения
|
||
|
||
3. **Создание групп**: Организуйте ссылки по категориямcp .env.example .env
|
||
|
||
4. **Добавление ссылок**: Добавьте свои социальные сети и сайты```
|
||
|
||
5. **Персонализация**: Выберите макет и цветовую схему
|
||
|
||
6. **Публикация**: Поделитесь своей персональной ссылкой### 2. Запуск проекта
|
||
|
||
|
||
|
||
### Для разработчиков```bash
|
||
|
||
# Запуск всех сервисов
|
||
|
||
Подробные инструкции по разработке и развертыванию:make up
|
||
|
||
|
||
|
||
- 📚 **[Руководство по Makefile](./docs/MAKEFILE.md)** - Все команды разработки# Применение миграций базы данных
|
||
|
||
- 🚀 **[Руководство по деплою](./docs/DEPLOYMENT.md)** - Развертывание в продакшенеmake migrate
|
||
|
||
- 🔧 **[Исправления и патчи](./docs/FIXES.md)** - Известные проблемы и решения```
|
||
|
||
|
||
|
||
## 🛠️ Разработка### 3. Доступ к приложению
|
||
|
||
|
||
|
||
### Режим разработки- **Frontend**: http://localhost:3000
|
||
|
||
```bash- **Backend API**: http://localhost:8000/api/
|
||
|
||
# Запуск для разработки- **Django Admin**: http://localhost:8000/admin/
|
||
|
||
make dev-bg
|
||
|
||
## Команды
|
||
|
||
# Просмотр логов
|
||
|
||
make logs-web # Backend- `make up` - Запуск всех сервисов
|
||
|
||
make logs-frontend # Frontend- `make down` - Остановка всех сервисов
|
||
|
||
- `make migrate` - Применение миграций
|
||
|
||
# Работа с базой данных- `make test` - Запуск тестов
|
||
|
||
make migrate # Применить миграции
|
||
|
||
make shell # Django shell## Структура проекта
|
||
|
||
make shell-db # Подключение к БД
|
||
|
||
``````
|
||
|
||
├── backend/ # Django приложение
|
||
|
||
### Тестирование│ ├── api/ # API endpoints
|
||
|
||
```bash│ ├── users/ # Пользователи
|
||
|
||
make test # Запуск тестов│ ├── links/ # Ссылки и группы
|
||
|
||
make lint # Проверка кода│ ├── customization/ # Настройки дизайна
|
||
|
||
make format # Форматирование кода│ └── backend/ # Настройки Django
|
||
|
||
```├── frontend/linktree-frontend/ # Next.js приложение
|
||
|
||
├── docker-compose.yml # Docker Compose конфигурация
|
||
|
||
### Работа с данными├── .env.example # Пример переменных окружения
|
||
|
||
```bash└── DEPLOYMENT.md # Подробные инструкции по развертыванию
|
||
|
||
make backup # Создать бэкап```
|
||
|
||
make restore # Восстановить из бэкапа
|
||
|
||
make clean # Очистить систему## Переменные окружения
|
||
|
||
```
|
||
|
||
Основные переменные в `.env`:
|
||
|
||
## 🚀 Деплой в продакшен
|
||
|
||
```env
|
||
|
||
### Простой деплой# Django
|
||
|
||
```bashDJANGO_SECRET_KEY=your-secret-key
|
||
|
||
make deployDJANGO_DEBUG=True
|
||
|
||
```DJANGO_ALLOWED_HOSTS=127.0.0.1,localhost
|
||
|
||
|
||
|
||
### С SSL сертификатом# PostgreSQL
|
||
|
||
```bashDATABASE_NAME=links_db
|
||
|
||
# Настройка SSLDATABASE_USER=links_user
|
||
|
||
make ssl-host-setup DOMAIN=catlinks.kr EMAIL=admin@catlinks.krDATABASE_PASSWORD=links_password
|
||
|
||
DATABASE_HOST=db
|
||
|
||
# Или ручная настройкаDATABASE_PORT=5432
|
||
|
||
make ssl-setup
|
||
|
||
make ssl-cert# Frontend
|
||
|
||
```NEXT_PUBLIC_API_URL=http://localhost:8000
|
||
|
||
```
|
||
|
||
📖 **[Подробное руководство по деплою](./docs/DEPLOYMENT.md)**
|
||
|
||
Подробнее в `DEPLOYMENT.md`.
|
||
|
||
## 🤝 Вклад в проект
|
||
|
||
## Особенности
|
||
|
||
Мы приветствуем вклад в развитие проекта!
|
||
|
||
- 🔐 JWT аутентификация
|
||
|
||
### Как принять участие:- 👤 Кастомизация профилей
|
||
|
||
1. Форкните репозиторий- 📱 Адаптивный дизайн
|
||
|
||
2. Создайте ветку для новой функции: `git checkout -b feature/amazing-feature`- 🔗 Управление ссылками и группами
|
||
|
||
3. Зафиксируйте изменения: `git commit -m 'Add amazing feature'`- 🎨 Настройка внешнего вида
|
||
|
||
4. Отправьте в ветку: `git push origin feature/amazing-feature`- 📊 API для всех операций
|
||
|
||
5. Откройте Pull Request
|
||
|
||
## Разработка
|
||
|
||
### Правила разработки:
|
||
|
||
- Следуйте существующему стилю кодаПроект настроен для разработки в Docker-контейнерах с горячей перезагрузкой.
|
||
|
||
- Добавляйте тесты для новых функций
|
||
|
||
- Обновляйте документацию при необходимостиДля разработки без Docker смотрите инструкции в `DEPLOYMENT.md`.
|
||
|
||
- Проверяйте код: `make lint`
|
||
|
||
## 📄 Лицензия
|
||
|
||
Этот проект распространяется под лицензией MIT. См. файл [LICENSE](LICENSE) для подробностей.
|
||
|
||
## 🆘 Поддержка
|
||
|
||
### Часто задаваемые вопросы
|
||
|
||
**Q: Как изменить порт приложения?**
|
||
A: Отредактируйте `.env` файл и измените переменные `FRONTEND_PORT` и `BACKEND_PORT`.
|
||
|
||
**Q: Как добавить собственные домены?**
|
||
A: Используйте `make ssl-host-setup DOMAIN=yourdomain.com EMAIL=your@email.com`
|
||
|
||
**Q: Приложение не запускается**
|
||
A: Проверьте статус: `make health` и логи: `make logs`
|
||
|
||
### Получить помощь
|
||
- 📖 Проверьте [документацию](./docs/)
|
||
- 🐛 [Создайте issue](https://github.com/smartsoltech/links/issues)
|
||
|
||
## 🙏 Благодарности
|
||
|
||
- [Next.js](https://nextjs.org) - за потрясающий React фреймворк
|
||
- [Django](https://djangoproject.com) - за надежный backend фреймворк
|
||
- [Bootstrap](https://getbootstrap.com) - за отличные компоненты UI
|
||
- Сообществу open source за вдохновение
|
||
|
||
---
|
||
|
||
<div align="center">
|
||
<p>Сделано с ❤️ командой <a href="https://github.com/smartsoltech">SmartSolTech</a></p>
|
||
<p>
|
||
<a href="#-catlink---персональные-страницы-ссылок">⬆️ Наверх</a> •
|
||
<a href="./docs/MAKEFILE.md">📚 Документация</a> •
|
||
<a href="https://github.com/smartsoltech/links/issues">🐛 Issues</a> •
|
||
<a href="#-вклад-в-проект">🤝 Contributing</a>
|
||
</p>
|
||
</div> |