This is a starter project for Craft 4 projects at One Design Company.
- Rename the
name:in the.ddev/config.yamlfile to match the name of your project. - Start DDEV by running
ddev startfrom the project root. - Run
ddev describeand make note of the database connection information as well as primary site url. - Fill out the appropriate values in the
.envfile. Sensitive data should be stored in a 1Password entry related to the project. - Install Composer dependencies:
ddev composer install. - Update Craft and plugins to latest stable versions:
ddev composer update. - Create an application key:
ddev craft setup/app-id - Set a security key in your
.envby typing:ddev craft setup/security-key - Use the correct version of Node and install front end dependencies:
ddev nvm use && ddev npm install. - Install Craft:
ddev craft install - (Optional) If importing an existing project, run
ddev import-db --file=dumpfile.sql.gz. If you'd like to use a database GUI, see the DDEV docs for available commands. - Start your vite server:
ddev npm start. - Fire up your site:
ddev launch.
ddev startddev npm run startddev launch
Local development is handled by DDEV, which means that the Craft application and its related services run inside of Docker containers provided by DDEV. For consistency and in order to avoid using binaries at different versions than the application requires, it is recommended that you run all project commands from within the DDEV containers.
DDEV provides wrappers for most things you will need (including the craft command), so you do not actually have to ssh into the container to run (most) commands. Examples:
ddev composer require foo/bar
ddev npm install
ddev npm run start
ddev craft project-config/apply
ddev craft plugin/enable imager-x
This project template comes with an .htaccess file that contains updates and optimizations for One Design Craft CMS projects. Once you have a production domain for you project, go into this file and update all the places where yourproject.com appears with the actual production domain.
Vite uses esbuild under the hood, and that compiles differently based on the system architecture of where it was installed. If you ran npm install outside of DDEV, then ddev npm run start will not work, because the container expects to be working with a version of esbuild that was installed from within the container.
If you have this issue, try rm -rf node_modules and then ddev npm install.
If you did initially run ddev npm install and your Vite server isn't working, be sure you're actually running ddev npm run start and not simply npm run start, as the project is configured to expect the Vite dev server to be running from with DDEV.
Because of the way that Vite resolves references to static assets, static assets referenced in your CSS or templates need to have an absolute URL with the static/ directory as the root. Examples:
A template image: <img src="{{ vite.url('/images/sprout.jpg') }}" alt="">
A font file: src: url('/fonts/fira-code-v21-latin-regular.woff2') format('woff2');
If you are referencing a Composer package that requires authentication, for example, a package hosted on Repman, you may need to authenticate while running ddev composer install. In a normal scenario, you would add an auth token to your global Composer configuration. With DDEV, you will need to add this token inside of the running web container.
ddev ssh
composer config --global --auth http-basic.onedesign.repo.repman.io token [your-token]
exit
Doing that will allow ddev composer install to succeed. The downside is that the container's global Composer config is ephemeral, so if you need to authenticate again for any reason, you will have to repeat the steps above.