readme.md

Teikirize bookmarks

Your self host solution for bookmarks saving.

You can see a live version here (not with admin access).

Last update: 23 March 2023

• 1. Features
• 2. Requirements
• 3. Updates from previous versions
• 4. Changelog
     • 4.1. 29 March 2023
• 5. Screenshots
• 6. Instalation
  • 6.1. Easy setup
    • 6.1.1. Quick run
    • 6.1.2. With some configuration
  • 6.2. Reset password
  • 6.3. Login
• 7. Libraries used
• 8. Security notes
• 9. Upgrades
• 10. New features or implementations
  • 10.1. Roadmap / PR suggestions
  • 10.2. Routes
  • 10.3. Custom theme or more javascript
  • 10.4. CSS customization
• 11. Troubleshooting

1. Features

• Easy to install and run
• SQLite database
• Less than 1Mb
• Insert, edit, delete bookmarks
• Automatically media info fetch from url
• Bookmarks can have tags associated
• Search bookmarks with text or tags
• Sort bookmarks by name or insertion date
• Private mode (only admin can see the stored bookmarks)
• Export bookmarks to a .json file
• Import bookmarks from a .json file (as long it is in the correct format)
• Redis ready
• Easily upgradable with new options/configurations

2. Requirements

php  >= 7.2
php curl extension
php SQLite3 extension
Redis (optional)

3. Updates from previous versions

You can replace all files except the database folder and update the /core/configs.php file with the new options.

4. Changelog

1 April 2023

• removed FILTER_FLAG_HOST_REQUIRED from url validation for php8.2 compatibility

4.1. 29 March 2023

• Search queries are now shareable (via url copy/paste)
• Changelog added to readme file
• Small bug fixes
• Added some details on the installation process
• fixed exporting bookmarks to use tags instead of tag ids
• Fixed a bug of tags with different cases being considered different
• Added a new option to the configuration file to allow the current user (manager) to clear cloudflare cache
• Added option to merge tags

5. Screenshots

Some context menus (click to view)

Administration (click to view)

Views (click to view)

Search examples (click to view)

Tags Merge

6. Instalation

6.1. Easy setup

6.1.1. Quick run

• Just upload all the files to your host.
• If not on the domain root (e.g. example.com or subdomain.example.com) you will need to edit the .htaccess line RewriteBase /bookmarks/ to your current path.
• Open the browser in your domain.tld and insert the admin password.
• You will probably need to set the /database folder permissions to 755 and the same to the file firstrun (if you get in a loop to set the password)

6.1.2. With some configuration

• Edit the /core/configs.php file

$items_per_page = 25; //set mumber of items to load per request
$redis = true; //redis will only be used if present, but can force not to use.
$redis_cache_time = 60 * 60 * 24 * 7 * 2; //2 weeks default, redis timeout
$private = false; // info is only show to logged in user (admin)
$base_path = get_base_url(true) . '/'; //should not change this

• If not on the domain root (e.g. example.com or subdomain.example.com) you will need to edit the .htaccess line RewriteBase /bookmarks/ to your current path.
• You can delete the assets/screenshots to save up some space
• Uploads all the files to your host (/docs folder can be ignored)
• Open the browser in your domain.tld and insert the admin password.

6.2. Reset password

To reset your password create a file in the root folder named firstrun and open your browser on the domain.tld and you will be prompted to set a password.

6.3. Login

If you log out, to login in again go to the route domain.tld/manage and login again.

7. Libraries used

• PHP-Auth to manage login and create uuids
• Axios Promise based HTTP client, ajax post

8. Security notes

• databases should not be in a "public_html" folder, although the .htacess denies access and no directory listing it is a good practice to change the location (update the location accordingly: core/auth.php and core/db.php)
• Since I made this to be a single user application, if you are going to change to multi-user bear in mind to double check all the user input.

9. Upgrades

I made this mainly to my personal needs, so unless my needs change or someone asks for some small implementation (or I find a bug) this should be the final version.

Pull Requests are welcome, nevertheless.

10. New features or implementations

If you want to make upgrades or changes to fit your needs or even to make a PR

10.1. Roadmap / PR suggestions

This doesn't mean I will develop them - one day might - but take this as suggestions or things I might do someday.

• Multi-search categories and text
• Themes
• User settings stored in database
• Store images+favicons locally
• Local Time-machine bookmark copy
• Shareable link for searches
• Tags with colors associated
• Multi user
• Better REDIS management

10.2. Routes

It is pretty easy to add a new route or edit current ones. In the index.php file there is an array $routes contaning the current routes. Besides the route for 404 and method not allowed you can add new ones following the format:

$routes = [
  ...
  'routes' => [
    [
      'method' => ['get', 'post'], //get, post or both
      'function' => 'fn', // function name to call
      'expression' => '/bookmark/([\w\d\-]+)' //regex to capture the path
    ],
  ];

10.3. Custom theme or more javascript

You can easily add extra .css and .js files to be loaded when calling the header (get_header) by passing the filenames as arguments, the folders for them would be assets/css/ and assets/js respectively:

  $js = ['animations.js','app.js'];
  $css = ['new_theme.css'];
  $title = 'My custom title';
  get_header($title,$css,$js);

10.4. CSS customization

All the .css files are compiled from the .scss and are stored in the assets/css folder.

11. Troubleshooting

• Keeps looping in the first run screen

Probably it doesn't have permissions to delete the firstrun file, change the folder permissions to 755 and should be fixed.