Pika

A very simple URL shortener that converts URLs into easy-to-remember English words for improved usability.

台灣繁體中文 請按這

---

Table of Contents 📖

• Why "Pika" ❓
• Features ✨
• Screenshots 📸
• Usage 🚀
  • Installation ⚙️
  • Admin Panel 🛡
  • Setting the Rate Limit 🕒
  • Changing the Default Port 🔌
  • Customizing the Dictionary 📚
• Build It Yourself 🛠
  • File Structure 🗄
  • Prerequisites ✅
  • Building 🚧
• Special Thanks 🙏
• Notes 📝
  • External Sources Used 💿
  • Known Bugs 🐛
  • Hidden Features 🙈
• Issues / Bugs? 🙋‍♀️

---

Why "Pika" ❓

Pikas are known for being tiny, moves fast and jumps high. So I named this project Pika to emphasise that it is tiny and runs fast.

Features ✨

Found randomly generated URLs too hard to remember? This project offers another solution:

• Generates user-friendly shortened URLs like https://example.com/apple.
• Shortened URLs can also be customized.
• Apple mobile web app capability—add it to your home screen for a full-screen app-like experience.
• Supports light and dark modes for a better user experience.
• Fully customizable dictionary for randomized URL shortening.

---

Screenshots 📸

Light Mode ⚪	Dark Mode ⚫
🏠⚪ Main page light mode	🏠⚫ Main page dark mode
🏠⚪🔗 Main page light mode with QR Code	🏠⚫🔗 Main page dark mode with QR Code
🛡⚪ Admin page light mode	🛡⚫ Admin page dark mode

---

Usage 🚀

Installation ⚙️

1. Download the release ZIP file from the release page. To build it yourself, please refer to Build It Yourself.
2. Unzip the file.
3. Run the setup script:

   bash setup.sh
   
   # If Docker requires root permission
   sudo bash setup.sh

4. Follow the prompts to enter variables and parameters.
5. You're all set!

Admin Panel 🛡

Access the admin panel at: https://example.com/admin

Default admin account:

username: admin
password: password

Remember to change the password after the first login.

Setting the Rate Limit 🕒

The rate limit is set in nginx. Default setting allows 10 requests per minute. You can modify the limit in docker/nginx/nginx.conf.

Customizing the Dictionary 📚

Customize the dictionary by editing the dictionary.txt file before installation.

To refresh the dictionary, run the setup script again. Please note that by doing so, you will lose all existing data.

Reserved Words: Avoid using the following reserved words: login, admin, logout, api, index, index.html, change_pass. These will be removed during setup without notice.

---

Build It Yourself 🛠

File Structure 🗄

Source Code 🧑‍💻

• Frontend: Built using Vite, located in the frontend folder.
• Backend: Built using Python FastAPI, located in the backend folder.

Docker 🐳

• docker/frontend: Contains built frontend files.
• docker/backend: Contains Python backend files.
• docker/nginx: Contains Nginx default.conf.

Prerequisites ✅

1. Node.js >= 22.20.0
2. Python >= 3.14.2

Building 🚧

Frontend 🌐

1. Navigate to the frontend folder.
2. Install dependencies:

   npm install

3. (Optional) Modify the code as you wish.
4. (Optional) Vite can be executed in development mode:

   npm run dev

5. Build the frontend:

   npm run build

6. Copy the dist folder to docker/ and rename it to frontend.

Backend 👨‍🔧

The FastAPI documentation is in https://example.com/api/v3/docs.

The authentication token is there to bypass the cookie for easy developing, so you only need either cookie or authentication token to access the locked part of API in the documentation.

The token is stored in the docker/backend/.env file.

If you want to modify the backend, follow these steps. Otherwise, copy the backend folder to docker/ and rename it to backend.

1. Navigate to the backend folder.
2. (Optional, take venv for example) Create a virtual environment:

   python -m venv venv

3. (Skip if not using a virtual environment) Activate the virtual environment:

    source venv/bin/activate

4. Install dependencies:

   pip install -r requirements.txt

5. Modify the code as you wish.
6. Run the backend in development mode:

   python app.py

7. After modifying the backend, copy the backend folder to docker/ and rename it to backend.

---

Special Thanks 🙏

Thanks to @xinshoutw for helping me out on this project 😄.

Thanks to Liang Ye for helping me to design the UI 🎨.

---

Notes 📝

External Sources Used 💿

• SVG file from Google Fonts

Known Bugs 🐛

• QR Code Styling: The QR Code generated by QR code styling may not be able to display correctly across different devices, especially on Safari of all platforms.

Hidden Features 🙈

• A hidden invisible admin button is placed in the center under the Shorten URL form in the home page.

---

Issues / Bugs? 🙋‍♀️

Encounter problems / bugs? Wanted to contribute new ideas? Feel free to open new Issues.