Skip to content
GRIMOIRY

Tear a project down

$ grim server:remove-project shop --env=staging

A staging copy has served its purpose, a client has left, or a project is moving to another server and the old place should not keep answering. grim server:remove-project undoes what grim server:add-project and every release since have put on the server, for one environment of one project. It is also the first half of handing a domain from an old project to a new one, with two flags that keep the parts worth keeping.

Usage

$ grim server:remove-project shop --env=staging           # one environment, after a prompt
$ grim server:remove-project shop                         # the project's default environment
$ grim server:remove-project shop --keep-ssl --keep-db    # free the domain, keep certificate and data
$ grim server:remove-project shop --force                 # no prompt, for scripts

Run it from anywhere. The host, the domain and the database name come from your ~/.grim/servers.json. --host overrides the host only.

Arguments and options

Remove a deployed project from server (containers, volumes, nginx, SSL, DB)

Usage

grim server:remove-project [--host HOST] [--env ENV] [--keep-db] [--keep-ssl] [--force] [--] <project>

Arguments

Argument Description
project Project name (required)

Options

Option Description
--host=HOST Server host or alias (overrides saved config)
--env=ENV Tear down only this environment of a multi-env project (production, staging, …). Without it, only the project's default environment is removed.
--keep-db Keep the MySQL database and user
--keep-ssl Keep the SSL certificate
--force Skip confirmation prompt

What it actually does

It names what is about to go and waits for an answer. The default is no. The question reads Remove project shop [staging] from 203.0.113.10?, followed by Will delete: containers, volumes, nginx config, SSL cert, database and, when there are any, the environments that stay registered.

Then, for the staging environment of shop:

  1. Stops the containers with docker compose down and deletes the stack's three volumes: public, storage and redis-data.
  2. Removes the nginx vhost grim-shop-staging.conf and reloads nginx.
  3. Deletes the Let's Encrypt certificate of the primary domain. Skipped with --keep-ssl.
  4. Drops the database and its user. Skipped with --keep-db.
  5. Removes /opt/shop-staging.
  6. Forgets the environment in servers.json. When it was the last one, the whole project is unregistered.

The summary says what was kept, what was dropped and which environments remain. The server itself stays registered, and so does every other project on it.

Nothing is backed up. The database is dropped, the volumes with uploaded files are deleted, and /opt/shop goes with the only copy of the .env and its APP_KEY. Take a database dump and run grim env:pull first if any of it may be needed again.

Pitfalls

Without a domain it refuses to start

The full message is shop has no domain, and there is no default one. Set deploy.domain (or deploy.environments.<env>.domain) in grim.json, or register the project with `grim server:add-project shop --domain=<domain>`. There is no default domain to fall back on, and the command will not guess which certificate to delete. It reads the domain from the project's record in servers.json, so you meet this on a machine that never registered the project, or with a mistyped --env. Run it from the machine that did, with the environment as it is registered.

Without --env it takes the default environment

On a project with production and staging that is normally production. The prompt shows the environment in brackets; read it before you answer. To remove a project entirely, run the command once per environment.

A green run is not proof

Every step on the server is allowed to fail quietly, so that a half-removed project can still be cleaned up. A step that could not do its work is ticked like the rest. Look at grim server:status afterwards and check that the containers are gone.

Your own certificate stays on the server

Only certbot's certificate is deleted. A pair uploaded with --cert and --key remains in /etc/ssl/grim-shop/ until you remove it by hand.

Handing a domain to another project

grim server:add-project refuses a domain that another project's vhost still serves. Retire the old project with both keep flags, then add the new one under the same domain. The vhost is gone, so the check passes. The certificate is still there for certbot to reuse, and the old database waits until you are sure nothing needs it.

$ grim server:remove-project oldshop --host=vps1 --keep-ssl --keep-db
$ grim server:add-project shop --host=vps1 --domain=shop.example.com

After it finishes

The domain no longer has a vhost, so nginx answers it with whatever site is its default. Remove the DNS record if the name is not coming back. To bring the project back later, start over with grim server:add-project and a release.

Questions

Are the images deleted too?

No. Pulled images stay in Docker on the server and keep their disk space. grim server:status shows how much of it can be reclaimed.

Does it touch the repository or my local project?

No. It works on the server and on servers.json. grim.json, including a deploy block that still names the host, is left as it is.

grim server:add-project

Give a project a home

Prepare one environment of a project on a production server, with its database, nginx vhost, certificate, compose stack and .env.

grim server:add-domain

Add a second domain

Serve a deployed project on one more domain, with the vhost, the Traefik rule and the certificate widened to cover it.

grim server:auth

Put a password on a site

Switch HTTP Basic Auth on or off for a deployed project, in the host nginx that stands in front of it.

grim server:status

Look over a server

List the servers you have registered, or look at one of them: its containers, its disk, Traefik and its projects.

grim env:pull

Fetch a server's .env

Copy the .env of a deployed environment into the project as .env.<environment>, to read it or to edit and push back.

Recipes that use it

Staging to production, one image

Register a staging environment next to production, name both in grim.json, release to staging, look at it, then send the same tag to production without building again.