Litecart

🛒 litecart - shopping cart in 1 file with card and cryptocurrency payment support

#basket #cart #ecommerce #ecommerce-platform #golang #stripe #stripe-payments #shopping-cart #payment #shop

🛒 What is litecart?

Litecart is an open source shopping-cart in 1 file of embedded database (SQLite), convenient dashboard UI and simple site.

[!WARNING] Current major version is zero (v0.x.x) to accommodate rapid development and fast iteration while getting early feedback from users. Please keep in mind that litecart is still under active development and therefore full backward compatibility is not guaranteed before reaching v1.0.0.

Video Example

Admin Panel Screenshots

🏆 Features

🚀 Simple and Fast: Enjoy a one-click installation process that gets your store up and running quickly, saving you time and effort.

💰 Support for Popular Payment Systems: Accept payments seamlessly with support for popular payment systems, ensuring a smooth checkout experience for your customers.

🔑 Sell Files and License Keys: Whether you're selling digital files or license keys, litecart has you covered, providing flexibility in the types of products you can offer.

⚙️ Lightweight and Efficient: litecart utilizes SQLite as its embedded database, eliminating the need for heavy databases like MySQL, PostgreSQL, or MongoDB. This results in a lightweight website that performs exceptionally well.

☁️ Easily Customizable: Modify and customize your litecart website effortlessly to match your branding and unique requirements, making it truly your own.

🧞‍♂️ Convenient Administration Panel: With a user-friendly dashboard UI, litecart offers a hassle-free administration panel, allowing you to manage your store, inventory, and orders with ease.

⚡️ Hardware Compatibility: Whether you're running litecart on a powerful server or a modest hardware setup, rest assured that it will work seamlessly, providing a consistent shopping experience for your customers.

🔒 Built-in HTTPS Support: Prioritizing security, litecart comes with built-in support for HTTPS, ensuring the safety of your customers' data.

🆓 Free Products Support: Offer free products to your customers by setting the product price to 0. Free products are automatically processed without requiring payment system integration, making it perfect for free downloads, samples, or promotional content.

🌐 Multi-language Support: Built-in internationalization (i18n) support allows you to create multilingual stores. By default, litecart includes support for English and Chinese languages. The language switcher is available in both the admin panel and the public site, making it easy to manage content in multiple languages and provide a localized shopping experience for your customers.

⬇️ Installation

litecart is engineered for easy installation and operation, requiring just a single command from your terminal. Besides the conventional installation method, litecart can also be set up and operated via HomeBrew, Docker, or any other container orchestration tools like Docker Compose, Docker Swarm, Rancher, or Kubernetes.

Install on macOS

The fastest method to install litecart on macOS involves using Homebrew. This will install the command-line tools and the litecart server as a combined executable. If you don't utilize Homebrew, adhere to the Linux instructions below for litecart installation.

brew install shurco/tap/litecart

Alternately, you can configure the tap and install the package separately:

$ brew tap shurco/tap
$ brew install litecart

Install on Linux

The most straightforward and recommended method to start using litecart on Unix operating systems involves installing and utilizing the litecart command-line tool. Execute the given command in your terminal and adhere to the instructions displayed on the screen.

curl -L https://raw.githubusercontent.com/shurco/litecart/main/scripts/install | sh

Install on Windows

The simplest and most recommended method to start using litecart on Windows is by installing and utilizing the litecart command-line tool. Execute the given command in your terminal and adhere to the instructions displayed on the screen.

curl -L https://raw.githubusercontent.com/shurco/litecart/main/scripts/install | sh

or download and unzip the latest version for Windows.

Run using Docker

Docker enables the management and operation of a litecart instance without requiring the installation of any command-line tools. The litecart Docker container includes all necessary command-line tools or even for server execution.

For Docker Hub:

docker run \
  -v ./lc_base:/lc_base \
  -v ./lc_digitals:/lc_digitals \
  -v ./lc_uploads:/lc_uploads \
  -v ./site:/site \
  --rm shurco/litecart:latest init

docker run \
  --name litecart \
  --restart unless-stopped \
  -p '8080:8080' \
  -v ./lc_base:/lc_base \
  -v ./lc_digitals:/lc_digitals \
  -v ./lc_uploads:/lc_uploads \
  -v ./site:/site \
  shurco/litecart:latest

or if use Github Packages Hub:

docker run \
  -v ./lc_base:/lc_base \
  -v ./lc_digitals:/lc_digitals \
  -v ./lc_uploads:/lc_uploads \
  -v ./site:/site \
  --rm ghcr.io/shurco/litecart:latest init

docker run \
  --name litecart \
  --restart unless-stopped \
  -p '8080:8080' \
  -v ./lc_base:/lc_base \
  -v ./lc_digitals:/lc_digitals \
  -v ./lc_uploads:/lc_uploads \
  -v ./site:/site \
  ghcr.io/shurco/litecart:latest

Run using Docker Compose

Docker Compose provides a convenient way to manage multiple containers and services. The project includes several Docker Compose configurations for different use cases.

Production Setup (docker/docker-compose.yml): This configuration includes the litecart application and an Nginx reverse proxy:

cd docker
docker-compose up -d

This setup includes:

litecart: The main application container with all required volumes
nginx: Reverse proxy server that listens on port 80 and forwards requests to litecart

The Nginx configuration is located in docker/nginx/nginx.conf and can be customized as needed.

Development Setup (docker/docker-compose_dev.yml): For local development, you can use the development configuration which includes MailHog for email testing:

cd docker
docker-compose -f docker-compose.yml -f docker-compose_dev.yml up -d

This adds:

mailhog: Email testing tool accessible at http://localhost:8025 for viewing sent emails

Combined Usage: To run both production and development services together:

cd docker
docker-compose -f docker-compose.yml -f docker-compose_dev.yml up -d

Initialization: Before starting the services, initialize the application:

docker-compose run --rm litecart init

Stopping Services:

docker-compose down

Run using Kubernetes

An example manifest for running on Kubernetes can be found in the /k8s/ folder (thanks @vuisme)

⬇️ Updating

[!WARNING] Before any update, be sure to make a backup of the ./lc_base folder and the ./site folder.

Update on macOS / Linux / Windows

The easiest way to update litecart to the latest version is to execute the command:

./litecart update

If there were changes in the database structure during the update, it is necessary to perform migration. To do this, you need to run the command from the litecart folder:

./litecart migrate

Update using Docker

Our mantra is to make updating a seamless experience. Simply download the new image and launch the container as you normally would. For example, if use Docker Hub:

docker stop litecart
docker pull shurco/litecart:latest # download new image
docker rename litecart litecart-backup # do image backup
docker run \
  --name litecart \
  --restart unless-stopped \
  -p '8080:8080' \
  -v ./lc_base:/lc_base \
  -v ./lc_digitals:/lc_digitals \
  -v ./lc_uploads:/lc_uploads \
  -v ./site:/site \
  shurco/litecart:latest

If there were changes in the database structure during the update, it is necessary to perform migration. To do this, you need to run the command from the litecart folder:

docker run \
-v ./lc_base:/lc_base \
-v ./site:/site \
--rm shurco/litecart migrate

Run using Kubernetes

An example manifest for running on Kubernetes can be found in the /k8s/ folder (thanks @vuisme)

🚀 Getting started

Getting started with litecart is as easy as starting up the litecart server

Default run for Linux/macOS:

./litecart serve

For Windows:

litecart.exe serve

When launched for the first time, necessary folders will be created in the directory with the executable file. The default links for access are:

http://localhost:8080 - website
http://localhost:8080/_/ - control panel

If you need to run on a different port, use the flag --http:

./litecart serve --http 0.0.0.0:8088

[!NOTE] Ports <= 1024 are privileged ports. You can't use them unless you're root or have the explicit permission to use them. See this answer for an explanation or wikipedia or something you trust more. Use: sudo setcap 'cap_net_bind_service=+ep' /path_to/litecart

📚 Commands

Usage:

./litecart [command] [flags]

Available commands:

init        Creating the basic structure
migrate     Migrate on the latest version of database schema
serve       Starts the web server (default to 0.0.0.0:8080)
update      Updating the application to the latest version

Global flags ./litecart [flags]:

-h, --help      help for litecart
-v, --version   version for litecart

Serve flags ./litecart serve [flags]:

--http string    server address (default "0.0.0.0:8080")
--https string   https server address (auto TLS)
--no-site        disable create site

🏦 Adding payment systems

Stripe

Stripe is a popular payment system that allows you to accept online payments from customers. It provides various tools and APIs for processing payments, including the ability to accept credit and debit cards, digital wallets, and bank transfers. Stripe ensures payment security, currency processing, and support for various payment methods.

To obtain the Secret key in Stripe, follow these steps:

Log in to your Stripe account on the official Stripe website. If you don't have an account, register for one.
In the top right corner, select the Developers section.
In the dropdown menu, choose "API Keys".
In the "Standard keys" section, you will find your "Secret key".

[!WARNING] Please note that the "Secret key" is confidential information that should be kept secure.

PayPal

PayPal is an online payment system that allows individuals and businesses to send and receive money over the internet. It enables payments for goods and services, as well as transfers between users. PayPal provides a secure and convenient way to make electronic payments.

To obtain a Client ID and Secret Key for using the PayPal API, you need to follow these steps:

To use the API, you will need a PayPal business account.
Go to the PayPal Developer website and sign in with your PayPal business account credentials.
In the Dashboard, find the "My Apps & Credentials" section and create a new application by clicking the "Create App" button.
On the application page, you will see your Client ID. It will be visible immediately after creating the application. To see the Secret Key, click on the "Show" button under the "Secret" label.

[!WARNING] Please note that the "Secret key" is confidential information that should be kept secure.

SpectroCoin

SpectroCoin is a payment system and cryptocurrency wallet that allows users to send and receive payments in various currencies, including cryptocurrencies such as Bitcoin, Ethereum, and others. It also offers currency exchange operations between different currencies and the ability to deposit and withdraw funds to bank accounts. SpectroCoin ensures the security of payments and cryptocurrency storage, as well as offering additional features such as debit cards.

To obtain a "Merchant ID", "Project (API) ID" and "Private key" in SpectroCoin, follow these steps:

Register on SpectroCoin if you don't have an account yet.
Log in to your SpectroCoin account.
Go to the "Business" section in the navigation menu.
Navigate to the "New project" section in the navigation menu.
Fill in the project name and make sure to enable the "Public key" section. A window with a "Private key" will appear, copy and save it. You can activate other options if needed.
After filling in the details, you will be redirected to the projects page. Go to the created project and in the header, copy the "Merchant ID" and "Project (API) ID".

[!WARNING] Please note that creating a project may require you to complete the verification process for your SpectroCoin account.
Please note that the "Private key" is confidential information that should be kept secure.

Dummy Payment

Dummy Payment is a built-in payment provider that comes pre-configured with litecart. It is designed for processing free products (products with a price of $0) and does not require any external payment system integration or API keys.

How it works:

Automatically activated when a customer's cart contains only free products (total amount = $0)
No payment processing occurs - orders are immediately marked as paid
Customers only need to provide their email address to complete the checkout
Perfect for free downloads, samples, promotional content, and lead generation

Key features:

No configuration required: Works out of the box, no setup needed
No API keys needed: Unlike other payment providers, Dummy Payment doesn't require any external accounts or credentials
Instant processing: Orders are processed immediately without waiting for payment confirmation
Full feature support: All standard features work with Dummy Payment, including email delivery, digital file downloads, license keys, and webhooks

When to use:

Selling free products or samples
Offering promotional content
Collecting email addresses for lead generation
Testing the checkout process during development

[!NOTE] Dummy Payment is only used for carts containing exclusively free products. If a cart contains both free and paid products, customers must use a regular payment system (Stripe, PayPal, or SpectroCoin) to complete the purchase.

🆓 Free Products

Litecart supports free products, allowing you to offer digital content, samples, or promotional materials at no cost to your customers.

Creating Free Products

To create a free product:

In the admin panel, navigate to Products and create a new product
Set the Amount field to 0 (zero)
The product will automatically display as "free" in both the admin panel and on the website

How Free Products Work

Automatic Processing: When a customer adds only free products to their cart (total amount = 0), the checkout process automatically uses the built-in Dummy Payment provider (see Dummy Payment section for details)
No Payment Required: Free products bypass all external payment system integrations - customers can complete their purchase with just an email address
Instant Access: After checkout, customers immediately receive access to free products via email, just like paid products
Mixed Carts: If a cart contains both free and paid products, customers must use a regular payment system (Stripe, PayPal, or SpectroCoin) to complete the purchase

Use Cases

Free products are perfect for:

Free downloads and samples
Promotional content and giveaways
Trial versions of digital products
Free resources and documentation
Lead generation (collecting email addresses)

Technical Details

Free products are identified by amount = 0 in the database
The Dummy Payment provider is automatically selected for carts with amountTotal = 0
All standard features work with free products: email delivery, digital file downloads, license keys, and webhooks
Free products are included in order history and cart management just like paid products
No external payment processing occurs - orders are immediately marked as paid when using Dummy Payment

🧩 For developers

The backend is developed in Go language. The frontend admin panel operates on SvelteKit and TailwindCSS.

There are a number of scripts (in the ./scripts folder) that simplify development:
./scripts/golang - Installs or updates a previously installed version of go (if needed).
./scripts/migration - Helps to work with migrations. For instance, the ./scripts/migration dev up command will apply new migrations from folder ./migrations, then implement the migrations from folder ./fixtures.
./scripts/sqlite - Optimizes the existing database.
./scripts/tools - Sets up the necessary environment for development (if needed).
./scripts/webscripts - For the basic site, updates vue3 to the latest version.
./scripts/clear - Removing hung golang or vite processes.

[!NOTE] I recommend running the ./scripts/migration dev up command. It will add test data to the database, which makes it easier to work with. For example, it will create products, transfer test images and create a test user for access to the admin panel:
login - user@mail.com
password - Pass123

Admin panel (frontend)

To develop the web interface of the admin panel, you need to start the litecart server (for example, execute the command from the project root go run ./cmd/main.go serve). All the code is located in the folder ./web/admin. The command cd ./web/admin && bun run dev will start the development server for the admin panel web interface. By default, it will be available at http://localhost:5173/_/.

Base site (frontend)

To develop the web interface of the base site, you need to start the litecart server (for example, execute the command from the project root go run ./cmd/main.go serve).
Run ./scripts/webscripts to download and install the necessary JavaScript libraries into the folder ./web/site/public/assets/js/. To update the styles, it is necessary to execute the command cd ./web/site && bun run build.
If you actively change styles, you can run the command cd ./web/site && bun run dev. It will monitor changes in files and automatically update the style file.

Customization and Deployment

For detailed information on how to customize the site design and deploy it on a separate server with Nginx, see Customization and Deployment Guide.

🗺️ ToDo

litecart has a roadmap and I try to work on issues in specific order and such PRs often come in out of nowhere and skew all initial planning with tedious back-and-forth communication.

Product in the form of files
Product in the form of license keys
Product returned via API to another site (example license keys)
Payment Stripe
Payment PayPal
Payment Square
Payment Adyen
Payment Checkout
Payment via Webhook
Support for payment using crypto
Support WebHook (@nicksnyder in #61)
Dummy Payment (@majiayu000 in #261)

👍 Contribute

If you want to say thank you and/or support the active development of litecart:

Add a GitHub Star to the project.
Tweet about the project on your Twitter.
Write a review or tutorial on Medium, Dev.to or personal blog.
Support the project by donating a cup of coffee.

You can learn more about how you can contribute to this project in the contribution guide.

Top categories

tailwind daisyui admin template popup mdsvex portfolio blog form ecommerce ui carousel auth dark seo image routing