BlurAdmin: AngularJS Bootstrap Admin Panel Framework

This guide provides comprehensive instructions for deploying and using BlurAdmin, an AngularJS Bootstrap Admin Panel Framework.

Prerequisites

Before you begin, ensure you have the following installed:

• Node.js: Version 6.x or higher.
  • Check your version with: node -v
• npm (Node Package Manager): Comes bundled with Node.js.
  • Check your version with: npm -v
• Git: For cloning the repository.
  • Check your version with: git --version

Installation

Follow these steps to get BlurAdmin up and running on your local machine:

1. Clone the repository:

   git clone https://github.com/akveo/blur-admin.git
   cd blur-admin
   

2. Install project dependencies:

   npm install
   

Configuration

BlurAdmin is primarily a front-end framework and generally does not require extensive server-side configuration or API keys for basic usage.

• Theming: You can customize the theme by modifying the Sass files located in src/app/theme/.
• Data: Data for components like tables (src/app/pages/tables/TablesPageCtrl.js), maps (src/app/pages/maps/map-bubbles/MapBubblePageCtrl.js, src/app/pages/maps/map-lines/MapLinesPageCtrl.js), and mail (src/app/pages/components/mail/mailMessages.js) are hardcoded in their respective controller/service files. For dynamic data, you would integrate with a backend API.

Build & Run

BlurAdmin uses Gulp for its build process.

Development Mode

To run the application in development mode with live-reloading:

gulp serve

This command will:

• Compile Sass, JavaScript, and other assets.
• Start a local development server.
• Open the application in your default web browser (usually at http://localhost:3000).
• Watch for file changes and automatically reload the browser.

Production Build

To create a production-ready build of the application:

gulp build

This command will:

• Minify and concatenate JavaScript, CSS, and other assets.
• Optimize images.
• Place the compiled and optimized files into the dist/ directory.

Deployment

BlurAdmin generates static assets, making it suitable for deployment on various static site hosting services or traditional web servers.

Static Site Hosting (Recommended)

After running gulp build, the dist/ directory contains all the necessary files for deployment.

• Netlify:

  1. Push your blur-admin repository to GitHub, GitLab, or Bitbucket.
  2. Sign up for Netlify and connect your Git repository.
  3. Configure Netlify:
     • Build command: npm install && gulp build
     • Publish directory: dist
  4. Deploy your site.

• Vercel:

  1. Push your blur-admin repository to GitHub, GitLab, or Bitbucket.
  2. Sign up for Vercel and import your Git repository.
  3. Vercel should automatically detect the project type. If prompted, set:
     • Build Command: npm install && gulp build
     • Output Directory: dist
  4. Deploy your site.

• GitHub Pages:

  1. Ensure your dist folder is committed to your repository.
  2. In your GitHub repository settings, navigate to "Pages".
  3. Select the master branch (or gh-pages branch if you prefer) and the /dist folder as the source.
  4. Save your changes. Your site will be deployed to yourusername.github.io/your-repo-name.

Traditional Web Server (Apache/Nginx)

1. Run gulp build to generate the production files in the dist/ directory.
2. Copy the entire contents of the dist/ directory to your web server's document root (e.g., /var/www/html for Apache or /usr/share/nginx/html for Nginx).
3. Ensure your web server is configured to serve static files from that directory.

Troubleshooting

• npm install fails:

  • Issue: Dependency conflicts or network issues.
  • Solution:
    • Clear npm cache: npm cache clean --force
    • Delete node_modules directory and package-lock.json (or npm-shrinkwrap.json), then run npm install again.
    • Ensure you have a stable internet connection.
    • Check your Node.js and npm versions against the recommended prerequisites.

• gulp serve doesn't open in browser or shows errors:

  • Issue: Gulp tasks failing, port already in use, or browser issues.
  • Solution:
    • Check the console output for specific Gulp errors.
    • If the port is in use, you might see a message like "Address already in use". Try stopping other services using port 3000 or configure Gulp to use a different port (this requires modifying the Gulpfile).
    • Manually navigate to http://localhost:3000 in your browser.

• Styling or JavaScript not loading after deployment:

  • Issue: Incorrect file paths in the production build or server configuration.
  • Solution:
    • Inspect your browser's developer console for 404 errors related to CSS or JS files.
    • Ensure the dist/ directory contents are correctly placed in your web server's root or the specified publish directory for static hosts.
    • Verify that base paths are correctly configured if your application is served from a sub-directory (e.g., yourdomain.com/blur-admin/). This usually involves modifying the index.html <base href="/"> tag or Gulp configuration.

• "Cannot GET /" after deployment:

  • Issue: Server not configured for single-page applications, especially when navigating directly to sub-routes.
  • Solution: For static hosting, this is usually handled automatically. For traditional web servers, you need to configure URL rewriting to redirect all requests to index.html.
    • Apache: Add a .htaccess file in your root with:

      <IfModule mod_rewrite.c>
        RewriteEngine On
        RewriteBase /
        RewriteRule ^index\.html$ - [L]
        RewriteCond %{REQUEST_FILENAME} !-f
        RewriteCond %{REQUEST_FILENAME} !-d
        RewriteRule . /index.html [L]
      </IfModule>
      

    • Nginx: In your server block configuration:

      location / {
        try_files $uri $uri/ /index.html;
      }