# More than one project on this server

> Source: https://www.allsweb.com/sixpanel/docs/multiple-projects
> Markdown for agents: https://www.allsweb.com/sixpanel/docs/multiple-projects.md
> Publisher: AllsWeb (www.allsweb.com)

Part of: SixPanel documentation

**What this page is for:** run a second (or third) complete 6ammart install on
the same server, each with its own domain, database and code.

**You need**

- A server with room to spare. Plan roughly 2 GB more RAM and 1–2 more CPU
  cores for each additional busy project.
- A domain for the new project, and its 6ammart code — a zip or a git
  repository.
- Your first project already working. Nothing about it changes.

Each install is called a **project**. Your first one is the default project.

## What a project actually is

On this server, one project is a real boundary, not a folder convention:

- its own **Linux user** (`six-<short id>`), which owns its code and uploads;
- its own **PHP-FPM pool**, so one project's PHP cannot read another's files
  and a crash in one does not touch the other;
- its own **database** and database user;
- its own **cache and session store** (Redis), running as its own service on a
  private socket only that project's Linux user can open, with its own password;
- its own **queue worker**, **scheduler**, **websocket service** and **customer
  website**, each a separate systemd unit named after the project;
- its own web server configuration and its own certificates;
- its own **settings environment**. The background services of a project are
  started with nothing from the panel's own settings file except the server
  timezone, so a project's `.env` is the only thing that decides which database
  its queue worker, scheduler and websocket service talk to.

The web server and the database server are **shared** by every project on the
machine.

> **The cache used to be on that list too**, and it was the wrong
> place for it. Every project used one cache service behind one password, and
> that password has to be inside each project's own settings file for its own
> site to work — so any project on the server could read, and change, what every
> other project had put there. That is not a small thing: a 6ammart shop keeps
> its mail password, its Firebase and Maps keys, its SMS gateway key and its
> payment gateway secrets in the cache, along with everyone's signed-in
> sessions. Each project now has its own cache service on a socket the
> other projects' users cannot open, and each has its own password. **Updating
> does it for you**: your cache is copied across, so nothing goes cold and
> nobody is signed out.

> **On older servers the settings-environment point above was not true**, and it mattered: every
> project's background services were started with the FIRST project's database
> name, user and password in their environment, and Laravel does not let a
> project's own `.env` override something already set there. On a server with
> two or more projects, the second project's queue worker, scheduler and
> websocket service were talking to the first project's database — so its own
> queued work (emails, notifications, exports) never ran, and the work it did do
> landed in the wrong place. Updating fixes it on its own; nothing to
> change by hand, and no data is touched. If you have been running more than one
> project, look at the first project's failed jobs afterwards.

## 1. Create the project

1. Open **Projects** (in the **Panel** menu group).
2. Press the create button.
3. Type the new project's **domain**. The panel derives everything else from
   it: the admin address, the website address, `www`, and the websocket
   address. Change any of them if you want.
4. Open **Advanced** if you want to choose the **short id** yourself; otherwise
   the panel picks one from the domain.
5. Read the summary and create it.

> **The short id can never be changed.** It is used in the name of the Linux
> user, the PHP pool, the database, the systemd units, the web-server files and
> the folder your code sits in. It must be 3 to 20 characters: lowercase
> letters, digits and hyphens, starting with a letter. The **project name**
> above it is only a label and can be changed at any time — see [Rename a
> project](https://www.allsweb.com/sixpanel/docs/project-name).

The job creates the Linux user, the folders, the PHP pool, the services and a
new empty database, then registers the addresses. If Cloudflare manages that
domain it also creates the DNS records — proxied — and gets the certificates
for the admin panel and the website, all in the same run, with each step shown
as it completes. It takes a minute or two, and your other projects keep running
the whole time.

New projects share ports 80 and 443, so there is **no new firewall change**.

## 2. Then install its code

The new project's card and its Overview page list what is still missing. Work
down it:

1. **Domain and HTTPS** — already done if Cloudflare handled it; otherwise add
   the A records at your DNS provider and press **Get free SSL**. See
   [Domains and HTTPS](https://www.allsweb.com/sixpanel/docs/domain-ssl).
2. **The admin app** — upload the zip or install from git. See [Install your
   6ammart code](https://www.allsweb.com/sixpanel/docs/install-app).
3. **The customer website** — optional. See [The customer
   website](https://www.allsweb.com/sixpanel/docs/customer-website).
4. **Automatic deploys** — optional. Each project has its own webhook
   addresses, built from **its own** domain, and each repository has its own
   secret. Switch to the project first, then copy the address from its
   **Deploys** page. See [Deploy and update your code](https://www.allsweb.com/sixpanel/docs/deploy-update).
5. **Backups** — one schedule covers every project. See
   [Backups](https://www.allsweb.com/sixpanel/docs/backups).

## 3. Moving between projects

Once you have more than one project, a switcher appears in the top bar. It
shows only while you are on a Project page — on a Panel page there is nothing
to switch, so it is hidden. Choose a project and every Project page — Overview,
Deploys, Domain & SSL, Database, Logs, App .env, SixPreflight, Advanced — acts
on that one.

The web address tells you where you are. A **Panel** page is a whole-server
page. A **Project** page carries the project in its address.

Over SSH, add `--project` to almost any command:

```
sudo sixpanel project list
sudo sixpanel project show shop2
sudo sixpanel logs php --project shop2 -f
sudo sixpanel db dump --project shop2
```

Without `--project`, commands act on the default project.

## 4. Sizing the server

Every project runs its own PHP workers, its own cache service, its own queue
worker and its own scheduler. The database and the web server are shared.

The cache is the one to understand, because it has a memory limit. The server
has ONE cache memory budget — six per cent of its RAM — and adding a project
**divides** that budget rather than adding to it: on a 4 GB server, one project
may hold 245 MB of cache, and three projects may hold 81 MB each. That is
deliberate. Giving every project the full budget would promise more memory than
the machine has, and the first busy hour would take it from the PHP workers.
Each extra cache service itself costs about 3 MB, which is charged against the
worker budget so the arithmetic stays honest.

You do not have to do anything about this — the panel re-divides it whenever
you add or remove a project, without restarting anything. It is here so that
"why did my cache limit go down when I added a shop?" has an answer.

A 2-core / 4 GB server is a one-project server. After you resize the server,
open **Settings** → **Auto-tune** and press **Apply tuning**, so memory and
worker counts are recalculated for the new hardware. The affected services pick
up the new sizes.

The panel's own sizing already knows how many projects there are: adding one
lowers the PHP workers each project gets, rather than promising memory the
machine does not have. That is deliberate and it was measured rather than
assumed — on a 2-core server with three projects, giving one busy shop 16 PHP
workers instead of 4 served **no more requests per second** and made the slowest
one-in-a-hundred page 57% slower, because four workers already keep two
processors busy. The extra workers only take turns, and each one costs memory.

The same arithmetic decides the database's open-table cache, which does grow
with the number of projects, since each project has its own set of tables.

## 5. Backups with several projects

Every backup run covers **every** project: one database dump per project, plus
each project's uploaded files and settings, all in one snapshot.

Restoring from the panel puts back the default project. If you need to restore
one of the others, contact support first — do not restore over a
several-project server on a guess.

## 6. Deleting a project

> **This cannot be undone.** If you ask for its data to be removed, every
> order, every user and every image of that project is erased for good. Nothing
> takes a backup for you first. Take one now, before you open the delete box:
>
> ```
> sudo sixpanel backup run full
> ```

1. **Projects** → the project's card → the delete link.
2. Read the box. By default its **database and files are kept** on disk, so
   they can still be recovered.
3. Ask for the data to be deleted too **only** if you truly want it gone — and
   only if you have that backup.
4. Type the project's short id into the confirmation box. The delete button
   stays inactive until what you type matches exactly.
5. Delete.

Deleting stops and removes that project's services, its PHP pool and its
web-server configuration, and can also remove its DNS records and certificates.
Your other projects are untouched. The default project cannot be deleted.

## How to check it worked

- **Projects** lists the new project, and its card reaches a finished state.
- `sudo sixpanel project list` shows the short id, the domain and how many of
  its services are up.
- Open the new project's domain in a browser and log in to its admin panel.

## If it went wrong

- **Creating the project failed** — read the job log on the **Projects** page.
  Disk space and memory are the usual causes; check with `sudo sixpanel disk`.
- **The new project shows the old one** — the domain is pointed at the wrong
  project. Check **Domain & SSL** with the right project selected in the
  switcher.
- **The server became slow after adding a project** — run `sudo sixpanel top`,
  and see the slow-server section in [When something is
  broken](https://www.allsweb.com/sixpanel/docs/troubleshooting). Usually the answer is more RAM, then **Apply
  tuning**.
- **`sixpanel project create` refuses** — that is on purpose. Creating a
  project builds a Linux user, a database, a cache service, a PHP pool, a
  service set, web-server files and their configuration as one operation, so it
  stays in the panel. A half-made project is worse than none.
- **Can one project read another's cache?** No. Each project's cache listens on
  a file (a "unix socket") inside a folder that only that project's Linux user
  may open, so another project is refused by the operating system before it can
  even offer a password. **Health** checks that folder's permissions on every
  run and reports it as a fault if it is ever widened.